communications user's guide - cincom smalltalk

Cincom Smalltalk™

ObjectStudio®

Communications User’s Guide

P40-3802-03

ObjectStudio 8.3

Cincom Smalltalk™ ObjectStudio® Communications User’s Guide Publication Number P40-3802-03 © 1988–1999, 2001, 2003, 2005, 2006, 2008-2011 Cincom Systems, Inc. All Rights Reserved CINCOM SYSTEMS, INC. MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE MATERIAL CONTAINED IN THIS MANUAL, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. The information contained in this manual is subject to change without notice. This manual contains proprietary information that is protected by copyright. All rights are reserved. It may not be photocopied, reproduced, or translated, in whole or in part, without the prior express written consent of Cincom Systems, Inc. See http://www.cincom.com/legal/terms.html for a list of Cincom trademarks and other trademarks that may appear in Cincom product documentation. All other trademarks are trademarks or registered trademarks of their respective companies. Cincom Systems, Inc. 55 Merchant Street Cincinnati, Ohio 45246-3732 USA PHONE: (513) 612-2300 FAX: (513) 612-2000 WORLD WIDE WEB: http://www.cincom.com Attention: Some Cincom products, programs, or services referred to in this publication may not be available in all countries in which Cincom does business. Additionally, some Cincom products, programs, or services may not be available for all operating systems or all product releases. Contact your Cincom representative to be certain the items are available to you.

http://www.cincom.com/legal/terms.html

http://www.cincom.com

Release information for this manual

Cincom Smalltalk™ ObjectStudio® Communications User's Guide, P40-3802-03, is dated February 16, 2011. This document supports Release 8.3 of ObjectStudio.

Cincom Technical Support for ObjectStudio

All customers Web: http://supportweb.cincom.com

USA customers Phone: 1-800-727-3525

Fax: (513) 612-2000 Attn: ObjectStudio Support

Mail: Cincom Systems, Inc. Attn: ObjectStudio Support 55 Merchant Street Cincinnati, OH 45246-3732 USA

Outside of USA All: Visit the support links at http://www.cincom.com to find contact information for your nearest Customer Service Center.

Document description This manual is written for ObjectStudio developers who have knowledge of the specific communication protocols discussed in each section.

http://supportweb.cincom.com

http://www.cincom.com

Communications User’s Guide, P40-3802 4 Contents

Contents

1. CommBuilder support ................................................................. 8 Getting started ............................................................................................ 8

Starting CommBuilder ............................................................................... 9 CommBuilder development cycle ................................................................ 11

Defining host screen objects .......................................................................... 12 Creating a screen object .......................................................................... 12 Editing a host screen object ...................................................................... 13 Starting the Host Screen Editor .................................................................. 13 Changing field information ....................................................................... 14 Field names and attributes ....................................................................... 14 Screen identification ............................................................................... 15 Removing fields ..................................................................................... 17 Adding and inserting fields ....................................................................... 17 Using the Screen Editor pop-up menu ........................................................... 19 Saving a host screen object ....................................................................... 20 Organizing the CommBuilder workplace ........................................................ 21 Working with host screen objects ............................................................... 22

Building an interface ................................................................................... 24 Starting Build Interface ........................................................................... 25 Generating the interface .......................................................................... 27 The default user interface ........................................................................ 28 Linking user interfaces to host fields ........................................................... 29

Linking host screens .................................................................................... 32 Screen Links tool ................................................................................... 32 Starting screen links ............................................................................... 32 Moving between screens .......................................................................... 33

Generated controller ................................................................................... 35 CommBuilder tool classes .............................................................................. 35

HostScreen class .................................................................................... 36 HostSession class ................................................................................... 38

Class CommController .................................................................................. 40

2. EHLLAPI support ..................................................................... 41 Introduction to EHLLAPI ................................................................................ 41 Typical uses for EHLLAPI ............................................................................... 42 Preparing to use EHLLAPI .............................................................................. 43

Loading EHLAPPI .................................................................................... 43 Recognizing the emulator ......................................................................... 44


Using online method references ................................................................. 47 Definitions ........................................................................................... 48

The EHLLAPI class ....................................................................................... 49 Class variables ...................................................................................... 49 Instance variables .................................................................................. 49 Prerequisite methods .............................................................................. 50 Class methods ....................................................................................... 50 Instance methods ................................................................................... 52 Screen position ..................................................................................... 52 Connect and disconnect services ................................................................ 53 Operator services: Querying and changing status ............................................. 54 Operator services: Waiting for the host ........................................................ 57 Operator services: Sending keystrokes .......................................................... 57 Operator services: Requesting update notification ........................................... 58 Presentation space services: Querying and setting the cursor .............................. 59 Presentation space services: Searching the presentation space ............................ 60 Presentation space services: Copying data ..................................................... 61 Device services: Intercepting keystrokes ....................................................... 64 Device services: Reserving and releasing the keyboard ...................................... 65 Device services: Trapping the closing of a session ............................................ 65 Utility services ...................................................................................... 66 Return codes ........................................................................................ 66 Emulator differences .............................................................................. 68

Working with EHLLAPI .................................................................................. 70 Creating an instance of class EHLLAPI .......................................................... 70 Connecting to the presentation space .......................................................... 71 Setting session parameters ....................................................................... 71 Performing tasks .................................................................................... 75 Disconnecting from the presentation space .................................................... 78 EHLLAPI example ................................................................................... 78

Keystroke mnemonics .................................................................................. 80 Mnemonics using uppercase letters ............................................................. 80 Mnemonics using lowercase letters or numbers ............................................... 81 Mnemonics using @A and @uppercase letters ................................................. 82 Mnemonics using @A and @lowercase letters .................................................. 83 Mnemonics using @A and @alphanumeric (special) characters ............................. 84 Mnemonics using special characters ............................................................. 84 Alphabetic, numeric, and symbol keys ......................................................... 84

3. APPC support ......................................................................... 85 APPC overview ........................................................................................... 85

Conversation sequence ............................................................................ 86 Conversation models ............................................................................... 87 Additional features ................................................................................. 87


APPC verb methods ..................................................................................... 88 Available methods .................................................................................. 88 Using compound verbs ............................................................................. 90

APPC implementation .................................................................................. 91 Configuration ........................................................................................ 91 Conversation sequence ............................................................................ 93 Determining the conversation state ............................................................. 95 Using the receiveAndPost: method .............................................................. 97 Creating an APPC server .......................................................................... 98 Using descriptors to convert data ............................................................... 98 Modifying the translation module ............................................................... 100 Handling errors .................................................................................... 101

Tutorial example ....................................................................................... 102 Modifying the tutorial files ...................................................................... 102 Building the server TP image .................................................................... 103 Configuring the requester ........................................................................ 104 Tutorial procedure ................................................................................ 105

4. TCP/IP support....................................................................... 106 Overview ................................................................................................. 106

Network communication ......................................................................... 106 Types of conversations ........................................................................... 107 ObjectStudio implementation ................................................................... 107

SocketAddress class .................................................................................... 108 Creating a SocketAddress ........................................................................ 108 Host parameter .................................................................................... 108 Service parameter ................................................................................. 108 Proto parameter ................................................................................... 109 Example of creating a SocketAddress .......................................................... 109

Creating a socket ....................................................................................... 109 Working with sockets .................................................................................. 110

Connection-oriented server ...................................................................... 110 Connection-oriented client ...................................................................... 111

Advanced socket operations .......................................................................... 112 Receiving data of arbitrary length .............................................................. 112 Setting a timeout .................................................................................. 113 Setting operation mode .......................................................................... 113

Descriptor class ......................................................................................... 113 Instance variables ................................................................................. 114

Asynchronous data transfer ........................................................................... 115 Overview ............................................................................................ 115 Asynchronous data transfer example ........................................................... 116


5. DDE support .......................................................................... 117 Overview of Dynamic Data Exchange ............................................................... 117

Client/server conversation ...................................................................... 117 DDE protocol hierarchy ........................................................................... 118 Starting a DDE conversation ..................................................................... 118 Holding a DDE conversation ...................................................................... 119

Using DDE ................................................................................................ 120 Enabling ObjectStudio DDE support ............................................................ 120 Creating a DDE server session ................................................................... 120 Registering the server ............................................................................ 121 Defining server response ......................................................................... 122 Creating a DDE client session .................................................................... 124 Defining client response .......................................................................... 125 Checking the status of the DDE session ........................................................ 126 DDE transactions ................................................................................... 127

DDE sample applications .............................................................................. 128 Starting the server and client applications ................................................... 129 Initiating the conversation ....................................................................... 130 Performing a request ............................................................................. 130 Setting values ...................................................................................... 131 Updating the client ............................................................................... 131 Executing commands ............................................................................. 132 Ending a conversation ............................................................................ 132

6. Opentalk Communication Layer ................................................. 133 Introduction to the ObjectStudio Opentalk Communication Layer ............................. 133

Opentalk background ............................................................................. 133 Port of the Opentalk Communication Layer to ObjectStudio .............................. 133

ObjectStudio Opentalk Communication Layer documentation .................................. 133

Index ...................................................................................... 134

Communications User’s Guide, P40-3802 8 Chapter: 1. CommBuilder support Section: Getting started

1. CommBuilder support Getting started

ObjectStudio CommBuilder helps you quickly create client/server applications that interface with a 3270 or 5250 host using the EHLLAPI support in Smalltalk. CommBuilder extracts field information from 3270 or 5250 host screens for easy reference and generates ObjectStudio class files to ease development work with the host application. CommBuilder helps generate:

♦ Host screen objects

♦ Corresponding user interface screens

♦ Navigation links between host screens

♦ Data links between the user interface and host screens

CommBuilder provides easy access to the field information on a 3270 or 5250 terminal emulation screen, including field position and length, attributes of the data (how it is displayed and whether or not it is editable), and the text currently displayed. The CommBuilder Host Screen Editor extracts information and allows you to specify the important portions of any host screen. It also allows you to specify field names and all data associated with a field. In addition, you can define your own fields to work with host screens that do not already have formatted fields. You can save this information in a file for cross-reference while you build an application.


With this field information, you can use a CommBuilder definition to build an application that interacts with the host screen. You can create a user interface from the 3270 or 5250 screen by selecting the fields and pressing a button. CommBuilder builds the interface based on these selections and generates methods that perform most of the processing required to manage the interface.

The generated interface can verify that the host screen is active, extract the current field text, and send user input back to the host. CommBuilder's class files handle field position and size, and extract or update screen information. The EHLLAPI class definition allows you to read or write data to the host session, search for text on a screen, and activate the emulator window programmatically.

The following sections explain how to load and start CommBuilder and outline the CommBuilder development cycle.

Starting CommBuilder The following topics describe how to set up the CommBuilder environment for development, with or without a live host connection, and how to start CommBuilder.

Prerequisites Before you set up CommBuilder, you must have installed the EHLLAPI Wrapper software on your machine (see “Introduction to EHLLAPI” on page 41).

Specifying the type of connection When you are developing an interface to a host screen, you will want to use a live host connection. However, when you are learning to use CommBuilder, you can use a simulated host connection. In this manual, we refer to examples using a simulated connection.


Live host connection If you have an active connection to the host, load the EHLLAPI class by performing these steps:

1. Select File ⇒ Load application from the ObjectStudio Desktop.

The Applications dialog box appears.

2. Select EHLLAPI Generic or your specific EHLLAPI emulator. If you specify Generic, you must initialize the EHLLAPI DLL. For information about how to do this, see “Introduction to EHLLAPI” on page 41.

3. Click Load.

4. Continue as described in “Loading and starting the CommBuilder application” on page 11.

Simulated host connection If you are learning to use CommBuilder and do not have an active connection to the host, load the EHLLTEST class, which simulates an active host session:

1. Select File ⇒ Load File from the ObjectStudio Desktop.

The File Open dialog box appears.

2. Select COMMBLDR/ehlltest.cls.

3. Click OK.

4. Continue as described in “Loading and starting the CommBuilder application” on page 11.

Communications User’s Guide, P40-3802 11

Loading and starting the CommBuilder application Once you have specified whether you are using an active or a simulated host connection, you can load the CommBuilder application into the ObjectStudio environment.

1. Select File ⇒ Load application from the ObjectStudio Desktop. The Applications dialog box appears. 2. Select CommBuilder. 3. Click Load. The Loading Application screen appears and loads the application. 4. Click Close to close the Applications dialog box. The CommBuilder icon appears on the ObjectStudio Desktop. 5. Double-click the CommBuilder icon to start CommBuilder. The CommBuilder workplace contains an icon for each active or simulated 3270/5250 emulator session available. It also contains icons, shown in the following table, that allow you to access CommBuilder functionality.

Icon Function

Accesses the Host Screen Editor.

Allows you to build a default user interface and launches the Designer.

Allows you to specify links between host screens.

Contains all previously saved host screens.

CommBuilder development cycle There are four stages in developing a CommBuilder application with an interface to a 3270 or 5250 host: 1. Extract and identify all screen information. 2. Build an interface to the host screen. 3. Create links among host screens. 4. Program to enhance the front end.

Throughout this guide, we refer to an example application with an interface to a 3270 customer-service application. Development for a 5250 host is similar, with some minor differences in terminology.

Chapter: 1. CommBuilder support Section: Getting started


Defining host screen objects The following sections explain how to extract and identify the information on a host screen.

Creating a screen object At the top of the ObjectStudio CommBuilder workplace window, shown below, there are Session icons, each of which is labeled with a letter. If you are using a live host connection, CommBuilder displays an icon for each session for which your emulator is configured. If you are using a simulated host connection, CommBuilder displays up to four simulated host connections at one time.

For each host screen that your ObjectStudio application will access, you must create a corresponding host screen object. The Session icons are template objects that you use to create host screen objects.

To create a new host screen object, drag one of the Session icons to an empty area of the CommBuilder workplace. Note that the new host screen object icon does not look like the Session icon, but it is similar to the Edit icon.

For example, if you dragged the Session A icon, the Template Session A icon would appear, as shown here:

To delete any CommBuilder host screen object or template object, select it and Edit ⇒ Delete or select Delete from the template object’s pop-up menu.

Chapter: 1. CommBuilder support Section: Defining host screen objects


Editing a host screen object After creating a new host screen object template, you must edit it to match the host screen. To do so, use the Host Screen Editor. The first time you edit a host screen object, CommBuilder extracts the field information from the current host or the host emulator session.

Starting the Host Screen Editor You can open the Host Screen Editor in three ways:

♦ Select Edit from the Template Session icon pop-up menu.

♦ Drag and drop the Template Session icon on top of the Edit icon in the CommBuilder desktop.

♦ Double-click the Template Session icon.

The first time you edit a screen object, CommBuilder prompts you to name it. Type a name for the screen and click OK. For example, you could name the screen “Logon Screen.”

After evaluating the information from the host session, the Host Screen Editor appears. It contains field information extracted from the host session, as shown here:


Communications User’s Guide, P40-3802 14 Chapter: 1. CommBuilder support Section: Defining host screen objects

Changing field information The Host Screen Editor allows you to add, change, and delete field information defined for this host screen. Select the field you wish to modify from the list of fields in the lower left corner of the screen. CommBuilder highlights the field’s position in the upper half of the window and displays the corresponding field information in the lower half of the window.

Field order By default, the fields are ordered as they are extracted from the host screen. You can change the order of fields by dragging the name of a field from the list to a new position in the list.

Field names and attributes By default, the fields are named Field1, Field2, etc. CommBuilder records their positions on the extracted screen, field lengths, row and column locations, and attributes.

Field setting Description

Position The position of a field is measured as its distance in characters from the upper left corner of the screen, which is 80 characters wide. For example, a field that begins at Row 3, Column 0 has Pos 241.

Length The length of a field is measured in characters. For example, a field that is two full lines has Len 160.

Row and column

CommBuilder calculates the row and column locations of each field based on its position.

Attribute The field attributes, such as Protected, Num Only, and Hidden, are defined by the host. CommBuilder extracts this field information from the host screen but does not change it.


If the host screen contains fields that are extraneous to your application, you can refine the host screen object by changing the current field information. To change current field information:

1. Select the field name from the list of fields.

The corresponding field information appears in the lower half of the Host Screen Editor window.

2. Highlight the contents of the appropriate field information box and type the new information.

If you inadvertently change the data in a field, click Undo Changes to restore the previous values.

3. To save the change, select another field from the list.

The original field name changes to the new name.

Screen identification CommBuilder provides methods for determining the active screen. Because these methods rely on accurate screen identification, you should identify every screen that you extract. If you do not specify a unique key field, programs generated to use this screen may not work as expected.

Screen identifier methods The methods that identify screens check all host screen objects in the application. For each screen, these methods compare the text in the key fields to text in the same fields on the current screen. If a match is found, the method returns the name of the screen. If multiple screen definitions match the criteria, only the name of the first one found will be returned. You cannot specify the order in which screens will be searched.

If there is text that identifies a screen but has no permanent field location, specify its position as 0. In this case, the methods will search the entire screen for the matching text.



Screen identifier attribute Each field has a Screen Identifier attribute. By default, the Screen Identifier contains the text extracted from the corresponding field on the host screen. You can identify each host screen by creating a unique combination of key fields and screen identifier text.

To identify a field as a Screen Identifier:

1. Select the field from the field list. For example, select Field 2.

If this field contains text in the extracted screen, that text appears in the Screen Identifier box.

2. If you wish, enter new text or edit existing text in the Screen Identifier text box.

We recommend that you do not change the text unless you are certain that a portion of the key field text will always be the same and a portion may change.

3. Check the Key Field Text check box:

If you make an error, click Undo Changes to restore the previous values.

4. To save the Screen Identifier, select another field from the list.

Key fields are identified by an asterisk (*) in the list of fields:


Communications User’s Guide, P40-3802 17 Chapter: 1. CommBuilder support Section: Defining host screen objects

Removing fields You can remove fields from your host screen object. For example, you may wish to remove fields that contain unneeded information or that serve as placeholders on the extracted screen. From the list of fields:

1. Select the field you wish to remove.

2. Click Remove Field.

The field you specified is removed from the screen definition and from the list of fields.

Adding and inserting fields CommBuilder allows you to create additional field definitions so that you can add fields that are not formatted on the host screen. Your application can use these additional fields to watch for additional key fields or to read and write information you specify to unformatted areas of the screen. If you have deleted a field that was formatted on the host screen from your host screen object, you can insert that field back into the host screen object.

To create a new field, you must specify the new name, position, and length. You can specify the new field as a screen identifier, if appropriate. To create a new field:

1. To insert the new field into the field list, select the field that it will precede.

Or

To add the new field to the end of the list, select any field.

2. Highlight the contents of the Name box and type a new, unique field name.


3. Specify the position and length of the new field.

Highlight the contents of the Pos box and type a new position. Then highlight the contents of the Len box and type a new length.

Or

Highlight the position of the new field in the screen box at the top of the Host Screen Editor window, as shown here, and click Query Screen.

CommBuilder enters the Pos and Len values and calculates the Row/Col

location.

4. If this is a key field, specify the key field text and check the Key Field Text check box.

5. To insert the new field into the list above the currently selected field, click Insert Field.

Or

To add the new field to the end of the list, click Add Field.



Using the Screen Editor pop-up menu The Screen Editor has a pop-up menu that allows you to perform the functions that affect the entire host screen object. To display the pop-up menu, place the cursor anywhere on the screen except on the field list and press mouse button 1. The pop-up menu appears:

Reread Host Reread Host rereads the current text of a host screen. This is helpful when you wish to determine whether a host screen has changed since you created your host screen object. This option does not modify or re-extract any field information.

When you select Reread Host, CommBuilder prompts you to specify the host session you wish to read:

Select the letter that designates the host session you wish to read, and then click Read Screen. CommBuilder displays the current screen information in the upper half of the Host Screen Editor window.

Then select each field in the field list in the Host Screen Editor to see if the host screen object has changed. You can manually change the field information without having to create the whole screen definition again.



Remove All Fields Remove All Fields is useful if you plan to use only a few fields in your host screen object. You can remove all of the field definitions from the extracted screen and then define the fields that you need by using Add Field and Insert Field, as described in “Adding and inserting fields” on page 17.

Save Save allows you to save changes to the host screen object without closing the Host Screen Editor. If you have already specified a file name, CommBuilder saves changes in that file. If you have not yet specified a file name, CommBuilder displays the Save As dialog box.

Save As Save As allows you to specify the name of the file in which to store the host screen object. By default, this is the screen name. To change it, type a new file name. Click OK.

Saving a host screen object After naming the host screen with which you are working, save your work in a file:

1. Close the Host Screen Editor by double-clicking on the system menu.

2. If you have not yet specified a file name for this host screen object, CommBuilder displays the Save As dialog box. CommBuilder prompts you to enter a file name. By default, the extension is .cls, so you do not need to enter the extension.

CommBuilder saves the host screen as an ObjectStudio class file definition, which you can load.

3. If you wish to store the file in a directory other than the default, select the appropriate destination from the Directories list.

4. Click OK.

The Host Screen Editor closes, and the icon that was labeled Template Session A is now labeled Logon Screen.



Organizing the CommBuilder workplace When you save a host screen object, it appears in the CommBuilder workplace. The Host Screens folder in the workplace is provided so you can easily locate all host screen objects.

To refresh the CommBuilder workplace, select Refresh from the Workplace pop-up menu. Refresh rebuilds the active session icons and moves all host screen objects into the Host Screens folder, sorted in alphabetical order. The CommBuilder workplace looks the same as when you started CommBuilder.

To edit any host screen object, double-click the Host Screens icon. The Host Screens folder opens, as shown in the following figure. Open the Host Screen Editor as described in “Starting the Host Screen Editor” on page 13.



Working with host screen objects When you have created a host screen object, you can work with it directly from the CommBuilder workplace and from the Host Screens window.

Host screen icons You can drag a host screen object icon to other icons in the CommBuilder workplace. The following table describes the functions of the workplace icons you can use in this way:

Icon Name Action

Edit Edits the host screen object in the Host Screen Editor.

Build Interface Generates a default user interface for the host screen object and launches the Designer.

Links Opens the Screen Link window.

Using the host screen pop-up menu You can also access a host screen object through the screen object’s pop-up menu, shown here:



The menu options are described here:

♦ Save. Generates a summary of the host screen object, shown in the following figure, and prompts you to specify the name of the file in which to save it. The default file name is temp.scr; you can specify any name and any directory.

CommBui l der Host Scr een Ext r act Ut i l i t yCopyr i ght - 1996 Vmar k Sof t war e. Al l r i ght s r eser ved.Dat e : Januar y 15, 1996Scr een Name : Logon Scr een Fi l e : F: \ OSTUDI O\ LOGONSCR. CLS3270 Sessi on I nf o : A 25 l i nes by 80 col umns 17 f i el ds | 1 2 3 4 5 6 7 | 01234567890123456789012345678901234567890123456789012345678901234567890123456789- - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -0 | Logon Scr een1 |2 |3 |4 |5 |6 | Ent er Logon I D: __________7 |8 | Ent er Passwor d: * * * * * * * * * *9 |10| New Passwor d: * * * * * * * * * *..23| PF1 Next Scr een PF2 Pr evi ous Scr een PF3 Logof f24|

Fi el d Name Posi t i on Len At t r Text ( 35 char act er s)- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -* Ti t l e 0, 19 ( 20) 12 P [ Logon Scr een] Fi el d4 6, 5 ( 486) 15 P [ Ent er Logon I D: ] Fi el d6 6, 22 ( 503) 10 [ __________] Fi el d8 8, 5 ( 646) 15 P [ Ent er Passwor d: ] Fi el d10 8, 22 ( 663) 10 H [ * * * * * * * * * * ] Fi el d12 10, 5 ( 806) 13 P [ New Passwor d: ] Fi el d14 10, 22 ( 823) 10 H [ * * * * * * * * * * ] Fi el d16 23, 0 ( 1841) 46 P [ PF1 Next Scr een PF2 Pr evi ous Scr een* = Key Fi el d ( scr een i dent i f i er f i el d)At t r i but esP = Pr ot ect ed N = Num Onl y M = Fi el d Modi f i ed

The summary lists the session from which CommBuilder extracted the data, the text CommBuilder extracted, the field names as they are currently defined, key field identifiers, and an attribute legend.



♦ Print. Prints a summary of the host screen object, as shown above.

♦ Build Interface. Uses the fields you specify to create a default user interface, and launches the Designer. You can use any of the features of the Designer to enhance the user interface.

♦ Screen Link. Allows you to specify links between screens by sending data or key names.

♦ Edit. See “Starting the Host Screen Editor” on page 13 and “Changing field information” on page 14.

♦ Rename. Allows you to change the screen name that you defined when you first extracted the screen.

Other components, such as the Build Interface and Screen Link options, use the screen name. If the screen name is changed, you may need to modify or rebuild other code so it functions correctly with the new screen name.

♦ Delete. Removes the screen definition from memory and the icon from the window but does not affect the source code, which is stored in the .cls file in which you saved the screen definition.

Building an interface When you have finished defining your host screen object, you can either manually create the host screen interface using the Designer, or you can use the ObjectStudio CommBuilder’s Build Interface tool to generate a corresponding default user interface. Build Interface allows you to include only the fields you want and specify the font and size of the characters in the generated interface. CommBuilder is fully integrated with the Designer so you can use any of the Designer’s features to enhance the generated interface, including defining host links to host screen objects. The EHLLAPI class methods handle communication with the emulator.

Chapter: 1. CommBuilder support Section: Building an interface


Starting Build Interface To build an interface for a host screen, select the Build Interface option from the host screen’s pop-up menu or drop the host screen object on the Build Interface icon. The Build Interface window appears:

Field information The Build Interface window displays field information defined for the screen. The fifth column, Item Type, denotes the type of interface item that CommBuilder will generate.

CommBuilder displays fields and generates form items based on the field attributes extracted from the host screen.

Field type Form item type

Num Only Numeric fields.

Hidden Password fields.

Protected with field modified Static Update text fields that the user cannot change but the system can change each time the screen is displayed, such as date, time, status, or information fields.

Protected with associated field text Static text fields that are not read or updated when the interface is opened.

Protected with text PF followed by a numeral

Buttons to which links can be attached.

All others Entry fields.



Creating buttons For any field that contains the text PF followed by a numeral, the Build Interface generates a button. For example, in the Logon Screen, CommBuilder finds the static text line:

PF1 Next Screen PF2 Previous Screen PF3 Logoff

Based on this line, the Build Interface automatically generates buttons for Next Screen, Previous Screen, and Logoff. You can create screen links using these buttons. If you do, CommBuilder will write the appropriate method for each button.

The Build Interface also generates a Send Data button with methods that automatically send all data from the entry fields to the host screen.

Excluding fields The interface you build can contain all of the fields listed in the Build Interface window, or a subset. You can exclude as many fields as you would like. To exclude fields, hold down the CTRL key and select the fields you wish to exclude. Excluded fields remain in the host screen object, but they will not appear in the generated interface.

Setting the interface font To specify the font and size used in the generated interface:

1. Click Interface Font.

The Interface Font dialog box appears, as shown here:

The Interface Font window allows you to choose the font and size you want, and whether it should be bold, italic, or both. The Example box displays a sample of the text style and size currently selected.

2. Specify the font and size.

3. Click OK to make the change, or click Cancel to abort the change.



Generating the interface To build the interface, click Build Interface from the Build Interface window. CommBuilder generates an interface using the fields and font you have specified, and displays it in the Designer window:

You can edit this interface in the Designer. For information on how to do this, refer to the ObjectStudio User Interface Guide, P40-3811.


Communications User’s Guide, P40-3802 28 Chapter: 1. CommBuilder support Section: Building an interface

The default user interface CommBuilder generates a default user interface that is complete and ready to run. No modifications are required.

Features of the interface Each generated interface contains:

♦ Screen verification methods that are called when the controller is opened.

♦ Methods and accelerator keys that are defined for all PF buttons.

♦ Return key methods for all entry fields and for the Send Data button.

♦ Updateable items that are linked to the host screen and are automatically retrieved and sent as required.

♦ Special methods that, when sent to the host, re-extract updateable field information from the same screen, open the controller for a new screen (with the same session name if possible), or activate an emulator session for an unknown screen.

♦ Error message boxes.

Testing the user interface If you are using a live host connection, you can run the user interface:

1. From the pop-up menu for the appropriate Session icon in the CommBuilder desktop, select Activate.

2. From the Designer, select File ⇒ Test interface.

Generated method You can add your own special processing and error handling to the methods that CommBuilder generates. For further information about these methods, see “Generated controller” on page 35.


Linking user interfaces to host fields Using the Designer, you can set up host links or update links to existing screen items. If you access the Designer through CommBuilder, you can link screen items to host screens, whether or not you used Build Interface to create the interface. For more information about linking within the Designer, refer to the ObjectStudio User Interface Guide, P40-3811.

You can link multiple host screens to a given interface. However, you must set up the links through CommBuilder so that your application can navigate through the screens without user intervention. Each host screen in your application must be uniquely identified by key field text. For further information, see “Screen identification” on page 15.

To set up a Designer Host Link or Update Link:

1. In the Designer, double-click the screen item for which you wish to set up a link.

The Form Entry Field Options dialog box for the item you selected appears:



2. From the Options dialog box, click Link or Update Link, as appropriate.

The Link Hookups dialog box appears:

3. To link to a host screen, select HostScreen from the first column of the Link Hookups dialog box.

In the second column, ObjectStudio displays the names of all screens that are currently loaded, and the fields and field types of the highlighted screen.

4. Select the field from the host screen to which you wish to link the interface screen item:



5. Click OK.

The Designer displays the Form Entry Field Options dialog box and notes the Link or Update Link you have specified, as shown here:

6. Click OK to close the Entry Field Options window.

7. Double-click the system menu to close the Designer.



Linking host screens You must specify the links between host screen interfaces so your ObjectStudio application can automatically navigate through the screens of the host application. ObjectStudio CommBuilder generates generic methods that allow access to host screens that are not currently active.

When you have two or more user interfaces loaded, you can define the navigation path between them. For example, a customer service application would include screens for logging on, entering information to search for customer records, and displaying the search results. The following figure illustrates the flow of control from one screen to another and the keys (such as PF3 and ENTER) that the user must press to navigate.

Customer Search Customer Edit

Main Menu

PF3

PF5

PF3

PF7

PF2and

ENTER

Screen Links tool The Screen Links tool allows you to specify how the application moves from the active screen to another screen. For example, you could specify how to move from the Logon Screen when it is active to the Customer Search screen or the Edit Customer Records screen.

Starting screen links To set up a screen link, either drag the host screen object to the Links icon, or select Screen Links from the host screen object’s pop-up menu. The Screen Link dialog box for the host screen object appears:

Chapter: 1. CommBuilder support Section: Linking host screens


Moving between screens CommBuilder provides two ways for an application to move from the currently active screen to another screen:

♦ Sending special keys (such as PF3 or ENTER) as a string from the user interface to the host session.

♦ Sending text from the user interface to the host session.

You can use one method or both at the same time. If you send text and a key, the application will send any data defined to specific fields to the host session, and then send the Send Key data string.

Sending a key To send a key from the active screen to the host:

1. Select the name of the screen to which the application should link. For example, the user can move from the current screen to the Customer Search screen.

2. In the Link Type box, select Send Key.

3. In the Key to send text box, type the key you want to send. To specify a PF key, type the at sign (@) followed by the number, such as @2:

For further information about keys, see the description of sendKey: in

“Class CommController” on page 40.

4. If you are finished specifying screen links, double-click the system menu to close the Screen Links window. Otherwise, select another screen to link to.



Sending data CommBuilder allows the application to send data from a field to the host session. For example, the user could type “EDIT” in a field called Action, and then press ENTER to move to the Edit Customer Records screen. To specify the data that the application should send from the user interface to the host session: 1. Select the name of the screen to which the application should link. For

example, the user can move from the current screen to the Search Results screen.

2. In the Link Type box, select Send Data. CommBuilder displays a list of all fields that do not have the Protected

attribute:

3. From the list of fields, select the field in which the user must enter the

text. In this example, it is “Action.” 4. In the entry field above the list, type the text that the user must enter. In

this example, it is “SEARCH.” Then press ENTER. The text appears in the list beside the field name:

5. To send the ENTER key, follow the directions in “Sending a key” on page 33,

using @E as the data string. 6. If you are finished specifying screen links, double-click the system menu to

close the Screen Link dialog box. Otherwise, select another screen to link to.


Communications User’s Guide, P40-3802 35 Chapter: 1. CommBuilder support Section: Generated controller

Generated controller The ObjectStudio CommBuilder’s Build Interface tool generates a subclass of CommController, which is a subclass of Controller. There are no instance variables in the generated class, but there are two methods generated: finishInit and hostItemLinks.

The finishInit method sets the screenName and sessionId instance variables of class CommController. It also calls the instance method hostItemLinks. This method builds a dictionary of all updateable interface items for the host screen from which the interface was built.

CommBuilder tool classes ObjectStudio CommBuilder includes a set of reusable methods that use the generated host screen definitions and enhance the EHLLAPI class methods. CommBuilder provides these classes:

♦ HostScreen. Manages the extracted host screen definitions.

♦ HostSession. A subclass of EHLLAPI. It uses HostScreen as a foundation to provide higher-level access to the EHLLAPI class.

You can use these classes for EHLLAPI development.

The following section contains tables that list the HostScreen class and instance methods and the functions they perform. The second section lists the HostSession instance methods and their functions.

Communications User’s Guide, P40-3802 36 Chapter: 1. CommBuilder support Section: CommBuilder tool classes

HostScreen class The HostScreen class contains methods that retrieve field definition information from a HostScreen object. CommBuilder uses these methods, listed in the following tables, when you use the Build Interface tool.

HostScreen class methods

Method Function

screens Returns a dictionary of all HostScreen objects loaded into the system. The dictionary contains a key for each screen name and a value of the associated HostScreen object.

HostScreen instance methods

Method Function

at: label Returns the field information stored at the label you specify. The argument label must be a Symbol identifying a field name. The field information is returned as a dictionary of field information, which includes #Position, #Length, and #Attribute data.

fieldOrder Returns the order of the fields as an array of field names.

fields Returns a dictionary of all fields with field information, including #Position, #Length, and #Attribute data.

ids Returns the idDict instance variable, which contains all key field information used to uniquely identify the screen. The dictionary contains the fieldName (key) and text (value). If the data at each of these fields matches that on a Host session, then the screen is identified.

isAvailableOn: session with: hostData

Checks the host session to determine if this screen is active. Use the idDict instance variable to compare data.

Name Returns the screen name (same as that stored in the screenDict).

Name: newName

Changes the screen name, updating the screenDict class variable to the new name.


Method Function

screenLinks Returns the linkDict instance variable. This dictionary contains the Screen Name (key) and a dictionary of all required data or keys to send to change the screen.

setFieldOrder: newFieldOrder

Sets new field order array; newFieldOrder is an array of fields stored in the fieldData dictionary.

setFields: newFields

Sets the fieldData instance variable dictionary, including #Position, #Length, and #Attribute data.

SetIds: newIds Sets the iDdict instance variable. The dictionary contains the fieldName (key) and text (value). If the data at each of these fields matches that on a Host session, then the screen is identified.

setScreenLinksTo: newLinks

Sets the linkDict instance variable. This dictionary contains the Screen Name (key) and a dictionary of all required data or keys to send to change the screen.

totalFields Returns the total number of fields extracted.

totalFields: total Sets the totalFields instance variable.


HostSession class You can use the HostSession class in place of the EHLLAPI class. When you do, all EHLLAPI methods are available to a HostSession object because HostSession is defined as a subclass of EHLLAPI. The methods listed in the following table are available:

HostSession instance methods

Method Function

activateEmulator Sends the Activate and Restore flags to the emulator window associated with this session. Combines connectPMWindowServices, changePMWindowStatusFlags:x:y:dx:dy:behind:, and disconnectPMWindowServices calls. Returns itself or Message.

at: fieldName Returns the string from the current screen at the specified field name.

at: fieldName put: text

Puts the specified text in the specified field location on the current screen.

buildErrorMessage: msg number: num

Builds a generic message object combining the message text (msg) and error number (num). Returns an object of class Message.

changeTo: screen Uses screen links to send data to change from current screen to host screen.

getFirstLine Returns the first line of data from the current host session.

getLastLine Returns the last line of data from the current host session.

getLine: line Returns the line of data from the current host session; line is expected to be a line number from 0 to (number of lines-1).

isActiveScreen Named: name

Checks to see if the current screen matches the screen name passed. Returns true, false, or a message.

lastError Returns the last EHLLAPI error number generated through HostSession methods.

lastFunction Returns the function name that generated the last EHLLAPI error.


Method Function

queryActiveScreen Loop through all HostScreen objects loaded into the system and check to see if the current screen matches the definition. Returns the name of the active screen or nil if no match is found.

queryAllFields Obtains all fields from the current session. Returns a dictionary of the field name and text at that field.

setActiveScreenTo: screenName

Sets the active screen parameters to the screen specified. The screen name must be a HostScreen label that is currently loaded into the system.

waitForPS Waits up to 60 seconds for presentation space to update. Returns true (screen updated), false (screen not updated), or an error message. Caution: This method alters the EHLLAPI session parameters.

waitForPSTimeout: time

Waits up to 1/2 second for presentation space to update. Returns true (screen updated), false (screen not updated), or an error message. Caution: This method alters the EHLLAPI session parameters.

Communications User’s Guide, P40-3802 40 Chapter: 1. CommBuilder support Section: Class CommController

Class CommController Class CommController is a subclass of the Controller class. The methods shown in the following table are available:

Method Function

AccessScreen Checks the current screen. Changes to the required screen if possible. Returns true if the screen to be accessed is active.

CheckCurrentScreen Checks the current screen and returns true if the screen to be accessed is active.

Close Disconnects currentSession from the host.

EHLLErrorDisplay: Displays errors in a generic message box.

getCurrentScreen Extracts all updateable fields from the host screen and inserts the data into the appropriate interface items.

postOpenInitialization Initializes the hostFieldLinks dictionary. Connects to the host session. Checks the current screen.

sendData Sends all entry field data to the appropriate host fields.

sendKey: Sends a special key (ENTER or PF) to the host, waits for a new host screen, and checks the new screen to determine which of the following is performed: ♦ If it is the original screen, then the method

rereads all updateable fields ♦ If the new screen is not known, the method

activates the emulator If the new screen has a controller with the same name, the method closes the current controller and opens the new controller

Communications User’s Guide, P40-3802 41 Chapter: 2. EHLLAPI support Section: Introduction to EHLLAPI

2. EHLLAPI support Introduction to EHLLAPI

The ObjectStudio development environment provides extensive support for EHLLAPI, the Extended High-Level Language Application Programming Interface. EHLLAPI enables you to communicate between host applications and ObjectStudio applications.

The EHLLAPI class forms the foundation for ObjectStudio support of EHLLAPI. ObjectStudio supports all IBM EHLLAPI verbs and several useful combinations of verbs.

EHLLAPI supports two families of IBM terminals, controllers, and associated software: 3270 and 5250. Both of these families use a synchronous protocol to communicate with the host. An application that you build with EHLLAPI can access all types of host-based data, as long as the required functions operate on 3270 or 5250 terminals.

When you create an EHLLAPI application, you typically transmit information on a screen-by-screen basis, where each screen is composed of individual fields.

You can use ObjectStudio EHLLAPI to communicate with all emulators that support the standard, single-entry-point EHLLAPI message. In addition to generic EHLLAPI access, ObjectStudio supports the Rumba 3270 emulator from Wall Data. This support offers additional services that are not available through generic support.

Communications User’s Guide, P40-3802 42 Chapter: 2. EHLLAPI support Section: Typical uses for EHLLAPI

Typical uses for EHLLAPI You can perform any task with EHLLAPI that a user can perform in a 3270 or 5250 emulation session. You can use EHLLAPI to capture data, replace user interfaces, and perform repetitive tasks. Some examples of using EHLLAPI are presented here:

Use Description

Replacing a user interface

You can construct a new Graphical User Interface (GUI) front end for an existing host application while preserving all of the existing logic. A well-designed GUI can improve the usability of a 3270 or 5250 character-based application. To replace a 3270 or 5250 user interface, use the Designer to reproduce some or all of the existing screens as ObjectStudio forms. The ObjectStudio forms can serve as the front end for the existing application. Advantages of this approach are that you can develop the new forms quickly and that you do not have to change the existing application. Note, however, that the new interface may not exactly duplicate a true GUI application, because its logic is not event-driven.

Automating repetitive tasks

You can automate tasks that would normally be performed in an emulation session. The program acts as an emulator macro to relieve the user of tedious tasks. You can make the macro available while working with the emulator. Alternately, you can make the macro start a new emulation session, perform its task, and then shut down the session.

Consolidating tasks The same data often appears in multiple applications. You can write a program to capture the data once in an ObjectStudio form; then you can automatically enter the information into multiple host programs.

Retrieving data from existing host applications

When writing new PC-based GUI applications, you often need to incorporate data that is only available through host-based query tools. The EHLLAPI interface allows you to access these tools transparently, create your query, and take the results from the emulator screen to use in your program. This feature allows you to develop new PC-based applications with access to legacy data.

Monitoring programs Use EHLLAPI to monitor user input into an emulator session. When monitoring, you can gain control of the session if the user needs assistance. You can also write program monitors that simply track the use of a host-based program.

Communications User’s Guide, P40-3802 43 Chapter: 2. EHLLAPI support Section: Preparing to use EHLLAPI

Preparing to use EHLLAPI Before using EHLLAPI in ObjectStudio, ensure that you have met the following prerequisites:

♦ Version 5.0 or higher of ObjectStudio is installed on your system

♦ The ObjectStudio EHLLAPI Wrapper is installed on your system

♦ A terminal emulator for Windows (such as Rumba) is installed and recognized by ObjectStudio

Loading EHLAPPI To load EHLAPPI into ObjectStudio:

1. Select File ⇒ Load application from the Desktop menu.

The system displays the Applications dialog box.

2. Select the EHLLAPI loadable application that you want to work with. For example, choose EHLLAPI Generic or EHLLAPI Rumba.

3. Click Load.

4. Click Close to return to the ObjectStudio Desktop.

5. Initialize the EHLLAPI Dynamic Link Library (DLL) (applies only to generic EHLLAPI support). Send the message initializeFor: to the EHLLAPI class. The parameter is a string that contains the name of your vendor’s EHLLAPI Dynamic Link Library (DLL). For example, initialize a DLL named ACS3EHAP:

EHLLAPI initializeFor: 'ACS3EHAP'.


Recognizing the emulator For the information in this section, we assume that the emulator has been successfully installed and a host session has been established. You should verify that the PATH statement contains your emulator.

Following are the steps that should be taken so that ObjectStudio recognizes your emulator (consult the appropriate subsection for your emulator):

Even though the emulator works properly, ObjectStudio may not recognize it unless you take the steps as listed.

EHLLAPI requires a short session name. In most cases, the short session name is established by the emulator.

Attachmate EXTRA! (16-bit) Check the following items to ensure that ObjectStudio can recognize the Attachmate EXTRA! (16-bit) emulator:

♦ Verify that the directory where the emulator is installed is in your path (default = EXTRAWIN).

♦ Verify that the short session name is specified. The easiest place to set the short session name is in EXTRA! Configurator.

Attachmate EXTRA! (32-bit) Check the following items to ensure that ObjectStudio can recognize the Attachmate EXTRA! (32-bit) emulator:

♦ Verify that the directory where the emulator is installed is in your path (default = Program Files\E!PC).

♦ Under Options ⇒ Global preferences ⇒ Advanced ⇒ EHLLAPI short name, place the path to your .EDP session file.

Chapter: 2. EHLLAPI support Section: Preparing to use EHLLAPI


IBM 3270 Personal Communications (16-bit) Check the following items to ensure that ObjectStudio can recognize the IBM 3270 Personal Communications (16-bit) emulator:

♦ Verify that the directory where the emulator is installed is in your path (default = PCOMWIN).

♦ Under Appearance ⇒ Window Setup, verify that the boxes are checked for each of the following: Short Session ID and Separator (-).

IBM 3270 Personal Communications (32-bit) Check the following items to ensure that ObjectStudio can recognize the IBM 3270 Personal Communications (32-bit) emulator:

♦ Verify that the directory where the emulator is installed is in your path (default = PERSONAL COMMUNICATIONS).

♦ Under Appearance ⇒ Window Setup, verify that the boxes are checked for each of the following: Short Session ID and Separator (-).

Netsoft NS/Elite and NS/ElitePlus (16-bit and 32-bit) No special considerations.

RUMBA (16-bit) Check the following items to ensure that ObjectStudio can recognize the RUMBA (16-bit) emulator:

♦ Verify that the directory where the emulator is installed is in your path (default = RUMBA).

♦ Under Session ⇒ EHLLAPI Configuration, check the box for EHLLAPI SDK and give the session a short name.


RUMBA (32-bit) Check the following items to ensure that ObjectStudio can recognize the RUMBA (32-bit) emulator:

♦ Verify that the directory where the emulator is installed is in your path (default = Program Files\walldata\RUMBA).

♦ When installing RUMBA, be sure to check the System Options checkbox. If this checkbox is not checked, there will be no API menu item under Options.

♦ Once the emulator is up, go to menu item Options ⇒ API ⇒ Identification and set the session short name. Under Configuration, check Convert null characters to spaces.

Generic EHLLAPI In addition to the specific emulators listed above, ObjectStudio also supports any emulator that is IBM EHLLAPI-compatible. Check the following items to enable ObjectStudio support for such an emulator:

♦ Verify that EHLLAPI Generic is installed.

♦ Verify that the directory where the emulator is installed is in the PATH statement.

♦ Specify the name of your emulator’s DLL that supports EHLLAPI, along with the procedure name for EHLLAPI within this DLL.

Finding the correct .DLL can require some experimentation. There may be many DLLs available, but they may not be identified in the emulator documentation. Look for “hll”, “hal”, or “hap” in the file name. If you are unsure, contact your emulator vendor.

Chapter: 2. EHLLAPI support Section: Preparing to use EHLLAPI


Using online method references This manual gives a brief description of EHLLAPI methods. For detailed information about each method, use the online method reference. The online reference describes each method, contains detailed information about parameters and return values, and lists possible error codes.

To display the online method reference:

1. Select Tools ⇒ Class Browser from the Desktop.

The Class Browser appears.

2. From the Classes list box, select EHLLAPI.

3. Select Instance or Class to display instance or class methods.

4. From the Methods list box, select the method for which you want to see reference material.

5. From the Class Browser menu, select Method ⇒ Reference.

The system displays reference material for the method you selected.

For more information about the Class Browser, refer to the ObjectStudio User’s Guide, P40-3807.


Definitions This section contains definitions of two important terms:

♦ Presentation space. A presentation space (PS) is the character-based screen associated with the host application. EHLLAPI allows you to build GUI screens to replace the presentation space. Typically, a presentation space is 80 columns by 23 lines, but the size can vary depending on how the terminal is set up.

Most presentation spaces are field-formatted, which means that each area of the screen is treated as a separate field. The application user navigates through the screen, perhaps by pressing TAB to move from field to field. Each field can have specific field attributes.

♦ Operator Information Area. The Operator Information Area (OIA) is an area of the screen, typically the last line, that stores information about the physical session connection. Typically, you can use the OIA to check the status of the session, such as whether the connection to the host is still valid or busy.

Communications User’s Guide, P40-3802 49 Chapter: 2. EHLLAPI support Section: The EHLLAPI class

The EHLLAPI class To support EHLLAPI, ObjectStudio provides the EHLLAPI class, which is a subclass of class Object. Each instance of class EHLLAPI represents a terminal emulation session that can receive messages. This section describes the variables and methods of the EHLLAPI class.

Class variables The following table describes the class variables in class EHLLAPI:

Class variable Description

getEAB Indicates whether Extended Attribute Bytes (EAB) should be returned on queries.

xlate Translates EABs to color graphics adapter format. This translation changes the type of information returned when the EAB feature is on.

commDLLName Indicates the name of the emulator’s EHLLAPI DLL.

Instance variables The following table describes the instance variables in class EHLLAPI:

Instance variable Description

psId Short name for the session.

psRows Number of rows in the presentation space.

psColumns Number of columns in the presentation space.

psSize Size of the presentation space.

longName Long name for the session.

codePage Codepage for the presentation space.

sessionType $D = 3270 and $F = 5250.

hostPS Host presentation space as a String object.


Prerequisite methods Some of the methods listed in this section have a prerequisite method. If a method has a prerequisite, the prerequisite must execute before the method executes.

Class methods The EHLLAPI class has the following class methods:

initializeFor: aString Prerequisite None

Description Initializes the emulator’s EHLLAPI DLL. The parameter is a string that is the name of your vendor’s EHLLAPI DLL.

newPsId name Prerequisite initializeFor:

Description Creates a new EHLLAPI instance using the short session name of a configured session.

querySessions Prerequisite initializeFor:

Description Returns a dictionary that contains details about each session that ObjectStudio recognizes. The details include: session ids, session type, and the number of rows and columns. For more details about this method, see “Using online method references” on page 47.


receiveFileParams: string Prerequisite initializeFor:

Description Receives files from a host session.

resetSystem Prerequisite initializeFor:

Description Reinitializes EHLLAPI to its starting state. When this method executes, the system resets the session parameters, disconnects all instances of the class, and releases any resources that the instances are holding.

sendFileParams: string Prerequisite initializeFor:

Description Sends files from a host session.

setSessionParamsTo: anArray Prerequisite initializeFor:

Description Sets session parameters, which control the functioning of many instance methods. For more information about this method, see “Setting session parameters” on page 71.


Instance methods These sections describe the instance methods in class EHLLAPI.

Screen position Before reading about instance methods, you should understand the following ways to express screen position in the EHLLAPI class:

♦ Use standard EHLLAPI. Each screen position is numbered relative to the upper left corner. Numbering begins at 1 and proceeds from left to right and top to bottom.

♦ Use a two-element array of x, y coordinates. The upper left corner of the screen has coordinates of { 0, 0 }.

For each behavior in the EHLLAPI class that concerns screen position, there are two methods—one that uses one number to express position, and one that uses the two-element array.


Connect and disconnect services The following methods connect an EHLLAPI session to its emulator session or disconnect it:

connectPS Prerequisite newPsId:

Description Performs a physical connection to the presentation space.

connectPSForNotifyHostUpdate Prerequisite newPsId:

Description Performs the following sequence of messages:

self connectPS.

EHLLAPI setSessionParamsTo:

{ #IPAUSE #NORESET #TWAIT #NEWOIA }

self startHostNotifyEventSource: #Both.

This method connects to a session using the following parameters: #IPAUSE, #NORESET, #TWAIT, #NEWOIA. As a result of executing this method, most applications are in a state in which they are ready to use EHLLAPI.

For a method that has a prerequisite of connectPS, connectPSForNotifyHostUpdate satisfies the prerequisite.

disconnectPS Prerequisite connectPS

Description Disconnects the session that was connected to most recently.

disconnectPSForNotifyHostUpdate Prerequisite connectPSForNotifyHostUpdate

Description Disconnects the session that was most recently started with connectPSForNotifyHostUpdate. Performs the following sequence of methods:

self stopHostNotify.

self disconnectPS.

Chapter: 2. EHLLAPI support Section: The EHLLAPI class


Operator services: Querying and changing status The following methods query and change the status of the emulator window and maintain programmed interaction with the host system:

changePMWindowStatusFlags: flags x: x y: y dx: dx dy: dy behind: behind Prerequisite connectPMWindowServices

Description Changes the screen. Allows you to change the position of the emulator window, or hide, show, minimize, maximize, or resize it.

changePSWindowNameTo: string Prerequisite newPsId:

Description Changes the name of the emulator’s window.

changeSwitchListLTNameTo: string Prerequisite newPsId:

Description Changes the name of the emulator’s entry in the task list.


codePage Prerequisite connectPS

Description Returns the value of the codePage instance variable.

connectPMWindowServices Prerequisite newPsId:

Description Connects to PM Window Services so that you can change the emulator’s window attributes.

disconnectPMWindowServices Prerequisite connectPMWindowServices

Description Signals that you are done changing the emulator window.

longName Prerequisite connectPS

Description Returns the value of the instance variable, longName, whose value is the long name of the session to which you are connected.

psColumns Prerequisite connectPS

Description Returns the value of the instance variable psColumns, which holds the number of columns in the presentation space.

psId Prerequisite newPsId:

Description Returns the value of the psID instance variable.


psRows Prerequisite connectPS

Description Returns the value of the instance variable, psRows, which holds the number of rows in the presentation space.

psSize Prerequisite connectPS

Description Returns the value of the instance variable, psSize, which is the size of the connected presentation space.

queryPMWindowCoordinates Prerequisite newPsId:

Description Returns the PM window coordinates for the presentation space window of the emulator.

queryPMWindowStatus Prerequisite newPsId:

Description Returns the PM window status for the presentation space window of the emulator.

resetPSWindowName Prerequisite newPsId:

Description For a PM emulation application that was previously changed by the changePSWindowNameTo: method, it resets the title.

resetSwitchListLTName Prerequisite newPsId:

Description For a PM emulation application that was previously changed by the changeSwitchListLTNameTo: method, it resets the switch list name.


Operator services: Waiting for the host The following methods handle waiting for the host:

pauseTime: time Prerequisite newPsId:

Description Waits for the specified length of time (the time parameter is expressed in half seconds). Use this method instead of implementing a timing loop that waits for a host event.

A host event interrupts pauseTime: under the following circumstances:

♦ The startHostNotifyEventSource: method has been performed

♦ The #IPAUSE session parameter is set

wait Prerequisite connectPS

Description Causes the system to wait until the presentation space is available or until the end of a timeout period. Specify the timeout period by setting the #TIMEOUT option with the setSessionParamsTo: method.

Operator services: Sending keystrokes The following method sends keystrokes to the host:

sendKeyValue: string Prerequisite connectPS

Description Sends a string containing an ASCII mnemonic representing a keyboard key to the host screen at the current cursor location. For a list of ASCII mnemonics, see “Keystroke mnemonics” on page 80.


Operator services: Requesting update notification The following methods request host update notification:

queryHostUpdate Prerequisite startHostNotifyEventSource:

Description Indicates whether the host updated the presentation space or the OIA since the last time that the startHostNotifyEventSource: method or the queryHostUpdate method executed.

startHostNotifyEventSource: eventSource Prerequisite newPsId:

Description Denotes the beginning of a session segment during which a host event may occur in either the presentation space or the operator information area. Once you execute this method, you can execute the pauseTime: method to wait for an event, or the queryHostUpdate method to determine whether an event occurred.

stopHostNotify Prerequisite startHostNotifyEventSource:

Description Ends the session segment started by the startHostNotifyEventSource: method.


Presentation space services: Querying and setting the cursor The following methods query and set the cursor position:

queryCursorLocation Prerequisite connectPS

Description Returns the position of the cursor in the presentation space. The result is an array of two elements. The first element indicates the success or failure of the operation. The second element is an integer that represents the cursor position.

queryCursorXY Prerequisite connectPS

Description Returns the position of the cursor in the presentation space. The result is an array of two elements. The first element indicates the success or failure of the operation. The second element is a two-element array containing the X and Y coordinates of the cursor in the presentation space.

setCursorLocationTo: position setCursorXYTo: xyArray Prerequisite connectPS

Description Sets the cursor location to the position denoted by the parameter.


Presentation space services: Searching the presentation space The following methods search the presentation space (PS):

searchForScreenContaining: value withTimeout: timeout Prerequisite connectPS

Description Searches for the host screen with the value denoted by the first parameter until it times out. The amount of time to wait until timing out is denoted in half seconds by the second parameter. The method returns True or False.

When using this method, it is recommended that:

♦ When possible, you specify a unique identifier for the value parameter.

♦ You be cautious about screen painting order when the host system is slow. If you search for a string in the upper left-hand corner of the screen, the system may find it before the host finishes painting the screen. In this case, you can end up reading incorrect data from the screen.

♦ You may want to look for several possible strings at the same time; for example, for a specific form or for an error message.

checkPSFor: aString Prerequisite connectPS

Description Searches the presentation space for the string specified by the argument aString.

searchPSFor: string from: position searchPSFor: string fromXY: xyArray Prerequisite connectPS

Description Searches the presentation space for a string starting at the specified position, and returns an array of two elements. The first element indicates the success or failure of the operation. The second element is an integer representing the string’s starting position, or 0 if the string is not found.


Presentation space services: Copying data The following methods copy data between ObjectStudio and either the host presentation space or the OIA:

copyFieldToStringPosition: position length: length copyFieldToStringXy: xyArray length: length Prerequisite connectPS

Description Copies characters from a field in the presentation space to a string. You can use this method only in a field-formatted presentation space.

copyNextInputFieldToStringFrom: search Prerequisite connectPS

Description Executes a copyFieldToString method on the field following the string contained in the parameter, search.

copyOIA Prerequisite connectPS

Description Returns an array with an array of symbols. The symbols are the settings of the OIA of the connected host session.


copyPS Prerequisite connectPS

Description Returns an array with a string representation of the contents of the presentation space.

copyPSToStringPosition: position length: length copyPSToStringXy: xyArray length: length Prerequisite connectPS

Description Reads from the presentation space starting at the position denoted by the first parameter, and transfers those characters to a string, which is returned in an array. The string’s length is denoted by the second parameter.

copyStringToFieldValue: string at: position copyStringToFieldValue: xy: xyArray Prerequisite connectPS

Description Copies the string denoted by the first parameter to the presentation space at the position denoted by the second parameter.

copyStringToNextInputFieldFrom: search value: value Prerequisite connectPS

Description Executes a copyStringToFieldValue method on the field following the string contained in the parameter, search.

copyStringToPSValue: string at: position copyStringToPSValue: string xy: xyArray Prerequisite connectPS

Description Copies the string to the presentation space at the location denoted by the second parameter.


findFieldLengthFrom: pos mode: mode findFieldLengthFromXY: xyArray mode: mode Prerequisite connectPS

Description Finds the length of a field (specified by the mode parameter) in a field-formatted presentation space. Returns an array with the field length.

findFieldPositionFrom: from mode: mode findFieldXYFromXY: xyArray mode: mode Prerequisite connectPS

Description Finds the position of a field (specified by the mode parameter) in a field-formatted presentation space. Returns an array with the field position.

queryFieldAttributeAt: position queryFieldAttributeXy: xyArray Prerequisite connectPS

Description Finds the attributes of the field at a specified position. Returns an array with an array of symbols representing the field’s attributes.

searchFieldFor: string from: position searchFieldFor: string fromXY: xy Prerequisite connectPS

Description Searches for the string in the first parameter, starting at the position denoted by the second parameter.


Device services: Intercepting keystrokes The following methods intercept keystrokes typed directly into the emulator:

getKey Prerequisite startKeystrokeInterceptKeys:

Description Returns the next key in the input buffer.

postInterceptStatusKeyAccepted: boolean Prerequisite getKey

Description Informs EHLLAPI that a keystroke obtained with the getKey method has been accepted or rejected. Signals a rejected keystroke by beeping.

startKeystrokeInterceptKeys: keys Prerequisite newPsId:

Description Enables the emulator to receive user input without passing keystrokes to the host.

stopKeystrokeIntercept Prerequisite startKeystrokeInterceptKeys:

Description Ends the filtering of keystrokes that started when the startKeystrokeInterceptKeys: method executed.


Device services: Reserving and releasing the keyboard The following methods reserve and release the keyboard. When you reserve the keyboard, you prevent the user from entering data directly into the emulator.

reserve Prerequisite connectPS

Description Locks the presentation space so that the user cannot enter data through the keyboard or through the mouse. Use this method to temporarily prevent the user from interacting with the emulation session.

release Prerequisite connectPS

Description Unlocks the presentation space so that it can accept keyboard and mouse input.

Device services: Trapping the closing of a session The following methods trap the closing of an Emulator Session:

queryCloseIntercept Prerequisite startCloseIntercept

Description Determines whether the user has tried to close the emulation application since the queryCloseIntercept method last executed.

startCloseIntercept Prerequisite newPsId:

Description Prevents the user from closing the emulation application.

stopCloseIntercept Prerequisite startCloseIntercept

Description Cancels the effect of executing the startCloseIntercept method:, and allows the user to close the emulation application.


Utility services The following methods convert the presentation space coordinates:

convertToPositionXy: xyArray Prerequisite connectPS

Description Converts an array representing a screen coordinate to a single number representing a position on the screen.

convertToXYPosition: position Prerequisite connectPS

Description Converts a single number representing a position on the screen to an array representing a screen coordinate.

Return codes All EHLLAPI methods return a numeric result code. This code indicates either a successful execution or a specific reason for failure.

Most methods use the return codes listed in the following table. The codes can have slightly different meanings for specific methods, so consult the online method reference for exact interpretation. Use the following table to assist you in writing standard error handlers.


Return code

Explanation

0 The function executed successfully, or no host updates occurred since the last message was issued.mn

1 The presentation space short-session ID was invalid, or the application was not connected.

2 A parameter error occurred.

4 The method could not execute because the presentation space was busy.

5 The method could not execute for a reason other than that stated for code 4.

6 A data error occurred because of an invalid parameter; for example, a length error caused truncation.

7 The presentation space was invalid.

8 A prerequisite method has not been performed.

9 A system error occurred.

10 The emulation program did not support the method.

11 The requested resource was unavailable.

12 The session stopped.

20 An invalid keystroke occurred, caused by the #ESC = option. For more information about parameter settings, see “Setting session parameters” on page 71. For more information about keystroke mnemonics, see “Keystroke mnemonics” on page 80.

21 The OIA was updated.

22 The presentation space was updated.

23 Both the OIA and presentation space were updated.

24 The string was not found, or the presentation space was unformatted.

25 Keystrokes were not available on the input queue.

26 A host event occurred. This code occurs with the queryHostUpdate method.

27 A Ctrl+Break key sequence ended a file transfer.

28 The field length was 0.

31 The keystroke queue overflowed, resulting in lost keystrokes.


Emulator differences This section describes variations in supported methods for:

♦ 3270 and 5250 emulators

♦ Rumba 3270 emulator

♦ Attachmate emulators

Differences between the 3270 and 5250 emulators Not supported for 5250. The following methods are supported for the 3270 emulator but are not supported for the 5250 emulator:

♦ startCloseIntercept

♦ queryCloseIntercept

♦ stopCloseIntercept

♦ sendFileParams:

♦ receiveFileParams:

♦ connectPMWindowServices

♦ disconnectPMWindowServices

♦ queryPMWindowCoordinates

♦ queryPMWindowStatus

♦ changeSwitchListLTNameTo:

♦ changePSWindowNameTo:


Methods with different implementations. The following methods have different implementations for 3270 and 5250 emulators. For information about the methods listed in this table, see “Using online method references” on page 47.

Method Notes

copyOIA Because of differences in terminal types, returns different data for 3270 and 5250 sessions.

queryFieldAttributeAt: The 3270 and 5250 emulators use different field attributes.

sendKeyValue: “Keystroke mnemonics” on page 80 lists the mnemonics supported by the two emulators.

Rumba 3270 emulator The Rumba EHLLAPI loadable application supports the additional method runProfileName:mode:. For more information about this method, see “Using online method references” on page 47.

The following methods are not supported by the Rumba EHLLAPI loadable application:






♦ resetSwitchListLTName

Communications User’s Guide, P40-3802 70 Chapter: 2. EHLLAPI support Section: Working with EHLLAPI

Attachmate emulators The following methods are not supported by the Attachmate 3270 emulator and may not be supported by other Windows emulators:




♦ changePMWindowStatusFlags:


♦ queryPMWindowCoordinates


♦ resetSwitchListLTName

♦ changePSWindowNameTo:

♦ resetPSWindowName

Working with EHLLAPI The following topics describe a typical way to use the EHLLAPI class. The section titled “EHLLAPI example” on page 78 contains an example that uses many of the techniques described in the following topics.

Creating an instance of class EHLLAPI Create an instance of class EHLLAPI by sending the newPsId: message to the EHLLAPI class. Include a character parameter indicating the short session name you wish to work with. This method returns an instance of class EHLLAPI initialized for the indicated session.

hostSession := EHLLAPI newPsId: $A.


Connecting to the presentation space Connect the EHLLAPI instance to its presentation space (PS) using the connectPS or the connectPSForNotifyHostUpdate message. After connection, no other program can use the presentation space until you send the disconnectPS or disconnectPSForNotifyHostUpdate message.

result := hostSession connectPSForNotifyHostUpdate.

Disconnecting. If you use the connectPSForNotifyHostUpdate message to connect, you must disconnect by sending the disconnectPSForNotifyHostUpdate message. If you use the connectPS message to connect, disconnect by sending the disconnectPS message.

Multiple connections. Connections of EHLLAPI instances are sequential; multiple instances cannot simultaneously perform methods that have connectPS as a prerequisite. When you create multiple instances of class EHLLAPI, the last instance to perform connectPS can execute methods that have connectPS as a prerequisite. After the last connected instance performs a disconnectPS, the previous instance that performed a connectPS is available to use.

As shown in the following illustration, if an application connects instances A, B, and C, in that order, only C is available for methods that require a connectPS. Once C performs a disconnectPS, instance B becomes available.

instance AconnectPSinstance B

connectPSinstance CconnectPS

instance AconnectPSinstance B

connectPSinstance C

connectPS

AvailableAvailable

Setting session parameters Use the EHLLAPI class method setSessionParamsTo: to set nondefault values for the EHLLAPI session. The session parameter settings control the function of many individual EHLLAPI methods. You can change them any time while using the EHLLAPI class.

Chapter: 2. EHLLAPI support Section: Working with EHLLAPI


Parameter The parameter to the setSessionParamsTo: method is an array. Each element is either a symbol or an array containing a symbol and a value. The symbol represents the type of setting. An accompanying value indicates the value to assign to the setting.

The following table lists the valid elements that you can include in the parameter. The elements that are presented together are mutually exclusive: if you include one element that appears in a table row, you cannot include any of the other elements that appear in the same table row.

Element Use with method Function

#NOATTRB #ATTRB

copyPS copyPSToString copyFieldToString

#NOATTRB converts unknown values to blanks. #ATTRB passes back all codes that do not have ASCII equivalents as their original values.

#SRCHALL #SRCHFROM

searchField searchPS

#SRCHALL scans the entire host presentation space. #SRCHFROM searches forward from or back to the given position, depending on whether the #SRCHFRWD or #SRCHBKWD session parameter is set.

#SRCHFRWD #SRCHBKWD

searchField searchPS

If #SRCHFROM is set: ♦ #SRCHFRWD searches forward from

the given position. ♦ #SRCHBKWD searches back from the

end of the presentation space to the given position.

#FPAUSE #IPAUSE

pauseTime: #FPAUSE pauses for the specified duration of time. #IPAUSE creates an interruptible pause: after performing a startHostNotify:, a host event ends the pause.

#NOQUIET #QUIET

sendFileParams: receiveFileParams:

#NOQUIET displays messages. #QUIET does not display messages.



{#TIMEOUT c} sendFileParams: receiveFileParams: wait

Specifies the time to wait for an unresponsive host before sending a break. For more information, see the table under “Timeout character table” on page 75.

{#ESC c} getKey sendKeyValue:

Specifies the escape character for keystroke mnemonics. The default escape character is $@. Blank is not a valid escape character.

#AUTORESET #NORESET

sendKeyValue: #AUTORESET prefixes all strings sent by sendKeyValue: with a reset. #NORESET increases the performance of sendKeyValue: by eliminating the reset prefix.

#TWAIT #LWAIT #NWAIT

wait getKey

#TWAIT causes the wait method to wait for up to one minute, while getKey waits until the user enqueues a keystroke before returning. #LWAIT (not recommended) causes the wait method to delay processing until the system is not busy before returning. The getKey method waits until the user enqueues a keystroke before returning. #NWAIT forces the wait and getKey methods to return immediately after checking the status.

#EAB #NOEAB


#EAB returns an attribute array with an entry for each character. For each character in the returned string, the attribute array contains symbols for color and highlighting. #NOEAB does not return an attribute array.



#XLATE #NOXLATE


#XLATE translates Extended Attribute Bytes (EABs) to color graphics adapter format. Translation changes the type of information returned when EAB is on. #NOXLATE does not translate EABs.

#CONLOG #CONPHYS

connectPS #CONLOG does not change to the connected presentation space upon successful connection. #CONPHYS brings the connected presentation space to the foreground, with its screen group, upon successful connection. It does not switch screen groups.

#NEWOIA #OLDOIA

copyOIA #NEWOIA returns the session’s OIA in ASCII format. #OLDOIA returns the session’s OIA in 3270 PC format. Not supported for 5250 emulation.

#CFGSIZE #NOCFGSIZE

connectPS querySessions

#CFGSIZE gets the size of the configured presentation space. Ignores host overrides of the size. #NOCFGSIZE returns the current size of the presentation space.

#TROFF #TRON

all methods #TROFF turns off the trace feature. #TRON turns on the trace feature. These values provide a convenient way to control the EHLLAPI trace feature of your communication software. You can also control the trace feature directly from the communication software.


Timeout character table Use the following table to select a timeout period for the {#TIMEOUT c} session parameter:

Character Value (Min) Character Value (Min)

$1 0.5 $8 4.0

$2 1.0 $9 4.5

$3 1.5 $J 5.0

$4 2.0 $K 5.5

$5 2.5 $L 6.0

$6 3.0 $M 6.5

$7 3.5 $N 7.0

Performing tasks You can access the full EHLLAPI message interface to complete your tasks. The following topics describe some common activities:

♦ Waiting for the system to become available. The emulator session must be available before it can accept any commands. Use the wait message to check the availability of the host presentation space. If the presentation space is busy, the method waits for a specified amount of time for the host to become available. To specify the waiting period, send the setSessionParamsTo: message and set the #TIMEOUT option.

Use the wait message after methods such as sendKeyValue: to allow enough time to complete before your application continues processing.

♦ Settle time. Some host systems can cause a terminal’s “busy” prompt to flicker, thus suggesting that the system is available when it is not. In this case, you must wait for a period of time for the system to become available. The waiting period is called settle time.


♦ Searching for system prompts. When the wait method returns 0, it indicates that the host is available for input. However, the original transaction may not have completed successfully. Therefore, after the host becomes available, use the searchField method, the searchPS method, or the searchForScreen to look for expected keyword prompts on the screen.

For best results, combine wait or pauseTime: messages with a search for a specific screen. ObjectStudio provides this combination of methods in the searchForScreenContaining:withTimeout: message. This method waits for a specific screen to appear within a timeout period and for the system to be enabled for input. For performance reasons, use this method in combination with the #IPAUSE session parameter.

♦ Querying the host for updates. Certain methods allow you to check whether the emulator display has changed since the last check. To use this feature:

1. Send the startHostNotifyEventSource: message. You can request notification of updates to the PS or the OIA, or to both.

2. After the method completes, you may send the message queryHostUpdate at any time. This method indicates whether an update has occurred.

3. If you no longer need update information, or if you want to disconnect the session, send the message stopHostNotify.

♦ Sending keystrokes to the host. To send keystrokes to the host, send the sendKeyValue: message. These keystrokes appear to the session exactly as if the user had entered them into the emulation application. The parameter is a String object containing characters and character mnemonics. The parameter can be no longer than 255 characters. For the character mnemonics, see “Keystroke mnemonics” on page 80.


♦ Intercepting user keystrokes. To intercept user keystrokes:

1. Send the startKeystrokeInterceptKeys: message. This message enables the emulator to receive user input without passing keystrokes to the host.

2. Send the getKey message to return the next key in the input buffer. Queued keys obtained with this method can be processed and optionally sent to the host using the sendKeyValue: method.

3. After each use of the getKey method, send the postInterceptStatusKeyAccepted: message to verify that the key was accepted.

♦ Modifying the emulator’s appearance. To manipulate the emulator on the screen:

1. Send the connectPMWindowServices message.

2. Send a message to change the screen. The changePMWindowStatusFlags:x:y:dx:dy:behind: method is most commonly used. This method allows you to change the position of the emulator window or hide, show, minimize, maximize, or resize it.

Other methods allow you to change the title of the emulator session’s window and its appearance in the program switch list (see “Using online method references” on page 47).

3. When finished modifying the emulator window, send the disconnectPMWindowServices message.

These messages are part of the standard EHLLAPI interface, but they may not be supported by every emulator. In particular, ObjectStudio support for the Rumba emulator supports these messages even though Rumba itself does not currently do so. Contact the manufacturer of your emulator if you have any questions.

Chapter: 2. EHLLAPI support Section: Working with EHLLAPI


Disconnecting from the presentation space Before disconnecting from the presentation space, terminate any messages that reserved the keyboard, started keystrokes, or closed intercepts. Then, send the appropriate disconnect message:

♦ If you connected with the connectPS method, disconnect by sending the disconnectPS message.

♦ If you connected with the connectPSForNotifyHostUpdate method, disconnect by sending the disconnectPSForNotifyHostUpdate message.

You can reconnect a disconnected session. If you do reconnect to a session, the session will be as it was just before you disconnected from it.

EHLLAPI example This section presents code that demonstrates a typical use for the methods in the EHLLAPI class. It logs on to a 3270 session and waits for each screen to appear. It uses the sendKey method to answer prompts.

Logon

| result |

"create a new object of class EHLLAPI"

sess := EHLLAPI newPsId: $A.

"connect to the host presentation space (PS)"

result := sess

connectPSForNotifyHostUpdate.

result ~~ 0 ifTrue: [

^self error: 'Session not available,

result code:' ++

result.

]."endif"


"check for the screen with user ID prompt"

(sess searchForScreenContaining:

'USER ID' withTimeout: 10) ifFalse: [

sess

disconnectPSForNotifyHostUpdate.

^self error: 'Could not find username screen'.

]. "endif"

"send 'TESTID' followed by the enter key"

sess sendKeyValue: 'TESTID@E'.

"wait for the system to become available"

sess wait.

"wait for the screen to appear with the

user PASSWORD prompt"


'PASSWORD' withTimeout:

10) ifFalse: [

^self error: 'Could not find password screen'.

]."endif"

"send 'PASSWORD' followed by the enter key"

sess sendKeyValue: 'PASSWORD@E'.

"wait for the system to become available"

sess wait.

"wait for the screen to appear with the READY prompt"


'READY' withTimeout: 10)

ifFalse: [

sess

disconnectPSForNotifyHostUpdate.

^self error: 'Could not find ready screen'.

]."endif"

sess disconnectPSForNotifyHostUpdate.

!"end logon"


Keystroke mnemonics The following sections list the mnemonics and ASCII characters that the getKey and sendKeyValue: instance methods use. In these tables, Y indicates that the mnemonic is supported by that emulation service; N indicates that the mnemonic is not supported.

Mnemonics using uppercase letters

ASCII mnemonic

Meaning

3270 support

5250 WSF support

@B Left (Back) Tab Y Y

@C Clear Y Y

@D Delete Y Y

@E Enter Y Y

@F Erase EOF Y Y

@H Help N Y

@I Insert Y Y

@J Jump (set focus under PM)

Y Y

@L Cursor Left Y Y

@N New Line Y Y

@O Space Y Y

@P Print Y Y

@R Reset Y Y

@T (Right) Tab Y Y

@U Cursor Up Y Y

@V Cursor Down Y Y

@X DBCS (Reserved) Y Y

@Y Caps Lock (no action)

Y N

@Z Cursor Right Y Y

You can use the @J key only with the SEND_KEY function. As a result, the destination logical terminal (LT) becomes the foreground session.

Chapter: 2. EHLLAPI support Section: Keystroke mnemonics

Communications User’s Guide, P40-3802 81 Chapter: 2. EHLLAPI support Section: Keystroke mnemonics

Mnemonics using lowercase letters or numbers

ASCII mnemonic

Meaning

3270 support

5250 WSF support

@0 Home Y Y

@1 PF1/f1 Y Y

@2 PF2/f2 Y Y

@3 PF3/f3 Y Y

@4 PF4/f4 Y Y

@5 PF5/f5 Y Y

@6 PF6/f6 Y Y

@7 PF7/f7 Y Y

@8 PF8/f8 Y Y

@9 PF9/f9 Y Y

@a PF10/f10 Y Y

@b PF11/f11 Y Y

@c PF12/f12 Y Y

@d PF13 Y Y

@e PF14 Y Y

@f PF15 Y Y

@g PF16 Y Y

@h PF17 Y Y

@i PF18 Y Y

@j PF19 Y Y

@k PF20 Y Y

@l PF21 Y Y

@m PF22 Y Y

@n PF23 Y Y

@o PF24 Y Y

@p Plus Key N N

@q End Y Y


ASCII mnemonic

Meaning

3270 support

5250 WSF support

@s Scroll Lock (no action)

Y N

@t Num Lock (no action)

Y N

@u Page Up N Y

@v Page Down N Y

@x PA1 Y N

@y PA2 Y N

@z PA3 Y N

Mnemonics using @A and @uppercase letters

ASCII mnemonic

Meaning

3270 support

5250 WSF support

@A@C Test N Y

@A@D Word Delete Y N

@A@E Field Exit N Y

@A@F Erase Input Y Y

@A@H System Request Y Y

@A@I Insert Toggle N Y

@A@J Cursor Select Y N

@A@L Cursor Left Fast Y Y

@A@N Get Cursor Y N

@A@O Locate Cursor Y N

@A@Q Attention Y Y

@A@R Device Cancel (cancels print presentation space)

Y N

@A@U Cursor Up Fast N Y

@A@V Cursor Down Fast N Y

@A@X Hexadecimal N Y

@A@Y Cmd (Function) Key N Y

@A@Z Cursor Right Fast Y Y


Mnemonics using @A and @lowercase letters

ASCII mnemonic

Meaning

3270 support

5250 WSF support

@A@9 3270=Reverse Video 5250=Destructive Backspace

Y Y

@A@b Underscore Y N

@A@c Reset Reverse Video Y N

@A@d Red Y N

@A@e Pink Y N

@A@f Green Y N

@A@g Yellow Y N

@A@h Blue Y N

@A@i Turquoise Y N

@A@j White Y N

@A@l Reset Host Colors Y N

@A@n Go Directly to Session 1 N Y

@A@o Go Directly to Session 2 N Y

@A@p Go Directly to Session 3 N Y

@A@q Go Directly to Session 4 N Y

@A@r Go Directly to Session 5 N Y

@A@t Print (personal computer)

N Y

@A@y Forward Word Tab

Y N

@A@Z Backward Word Tab Y N


Mnemonics using @A and @alphanumeric (special) characters

ASCII mnemonic

Meaning

3270 support

5250 WSF support

@A@- Field - N Y

@A@+ Field + N Y

@A@< Record Backspace N Y

Mnemonics using special characters

ASCII mnemonic

Meaning

3270 support

5250 WSF support

@@ @ Y Y

A/ Overrun of queue (Only in the GET_KEY function)

Y Y

@$ Alternate cursor (Presentation Manager only)

Y N

@< Backspace Y Y

Alphabetic, numeric, and symbol keys The following alphabetic, numeric, and symbol keys are supported on both the 3270 and 5250 emulators:

♦ Lowercase letters a–z

♦ Uppercase letters A–Z

♦ Numerals 0–9

♦ Symbols ~ # ! $ % & ( ) * + ' - . / : ; < > = ? { } [ ] |

Communications User’s Guide, P40-3802 85 Chapter: 3. APPC support Section: APPC overview

3. APPC support APPC overview

The Advanced Program-to-Program Communication (APPC) protocol allows peer-to-peer communications between programs in a Systems Network Architecture (SNA) environment.

An application using the APPC protocol is termed a Transaction Program (TP). One program is the initiator and the other is the acceptor TP. Each TP uses a Logical Unit (LU) to access the network. A Logical Unit represents one computer connected as a node to the SNA environment.

APPC permits communication between any SNA LU 6.2 nodes that support the APPC protocol. These nodes can be connected by a Local Area Network or by a Synchronous Data Link Control (SDLC). Your APPC applications can distribute processing among other LU 6.2 nodes.

The communications software installed on your machine manages the low-level flow of data between nodes. In addition, the communications software allows TPs to exchange data with other LU 6.2 nodes. This data management allows your PC-based application to communicate with nonhomogeneous hardware, such as a mainframe host. Several TPs can use the same LU.

Before two TPs can communicate, you must establish an LU-to-LU session, which is the logical connection between the two units. The session’s mode determines how data moves between the two LUs.

Communication between the two TPs occurs as a conversation, and a TP can be involved simultaneously in multiple conversations. Conversations are carried out by issuing APPC verbs to begin the conversation, send data, receive data, and end the conversation.


Conversation sequence The APPC protocol supports TP communications on a peer-to-peer level. Depending on your requirements and design, your ObjectStudio application may both request and provide a service. Conversation partners must be aware of changes in conversation states.

When beginning a conversation, one TP acts as the initiator and the other as the acceptor. This distinction holds until both partners acknowledge the start of the conversation. Thereafter, either partner can send data, receive data, or terminate the conversation.

During a conversation, only one TP can send data at a time. The sending TP retains the right to send until it is explicitly surrendered. If the receiving TP requests to send, the sender must grant that right.

The exchange of data between sender and receiver continues until one of the TPs terminates the conversation. Under normal conditions, the sending TP terminates the conversation. If the receiving TP terminates the conversation, the sending TP is notified on its next attempt to continue the conversation.


Conversation models A conversation model serves as a script for APPC conversations within your applications. The model is a protocol selected by the conversation developers. This protocol dictates the sequence in which APPC verbs are sent and received. Many factors influence the conversation model:

♦ Frequency of communication

♦ Amount of data transmitted

♦ Network capacity

♦ Application performance requirements

♦ Scripting capabilities of the TPs

For example, the single-request-return conversation model is highly scripted. Think of the ObjectStudio application as a client making requests of a server. If requests are infrequent (a relative term defined by network capacity and performance requirements), the model limits the conversation to a single request and its associated response. Thus, each time the ObjectStudio application requests a service, it initiates a conversation. The accepting TP accepts both the conversation and the service request. After the accepting TP performs the service, it returns the results to the initiating TP along with a termination notice.

Highly scripted conversations, as described here, are generally easier to implement, troubleshoot, and maintain. However, if you cannot script the specific sequence of APPC verbs in a conversation, you may use a more flexible, and potentially more complex, model.

Additional features The APPC protocol allows synchronized conversations, which require confirmations after certain requests. To provide more structured control, you must specify the confirmation synchronization level when allocating the conversation. APPC also supports different levels of security that can be implemented to protect conversations. The initiating TP registers a USERID and PASSWORD, which the accepting TP’s LU checks upon receipt.

Communications User’s Guide, P40-3802 88 Chapter: 3. APPC support Section: APPC verb methods

APPC verb methods The ObjectStudio APPC class contains methods that correspond to the required APPC conversation verbs. These methods simplify the process of designing APPC applications by removing the overhead needed to generate the proper data structures.

Available methods The following table describes the available methods:

Method Function

allocate [MC_]ALLOCATE

Allocates a session between the local and partner LUs. With the RECEIVE_ALLOCATE verb, establishes a conversation between initiating and accepting TPs.

confirm [MC_]CONFIRM

Sends the contents of the local LU send buffer and issues a confirmation request to the partner TP. The partner TP responds with the [MC_]CONFIRMED verb or the [MC_]SEND_ERROR verb. The TP can only execute this method if the sync level was set to #Confirm when the conversation was allocated.

confirmed [MC_]CONFIRMED

Replies to the [MC_]CONFIRM verb from the partner TP. Indicates that no error was detected.

conversationType GET_TYPE

Returns the conversation type, either #Basic or #Mapped.

deallocate [MC_]DEALLOCATE

Deallocates a conversation between two TPs.

flush [MC_]FLUSH

Sends the contents of the local LU’s send buffer.

getAttributes [MC_]GET_ATTRIBUTES

Returns the attributes of the conversation.

prepareToReceive [MC_]PREPARE_TO_RECEIVE

Changes the local TP conversation state from #Send to #Receive.

receiveAllocate RECEIVE_ALLOCATE

Replies to the [MC_]ALLOCATE verb to establish a conversation.


Method Function

receiveAndPost: [MC_]RECEIVE_AND_POST

Receives data and status information asynchronously from the partner TP.

receiveAndPost:descriptor: [MC_]RECEIVE_AND_POST

Receives data and status information asynchronously from the partner TP using the specified descriptor.

receiveData [MC_]RECEIVE_AND_WAIT

Receives data and status information from the partner TP. If no data is available, the method waits for data to arrive.

receiveDataDescriptor: [MC_]RECEIVE_AND_WAIT

Receives data and status information from the partner TP using the specified descriptor. If no data is available, the method waits for data to arrive.

receiveImmediate [MC_]RECEIVE_IMMEDIATE

Receives data and status information from the partner TP. If no data is available, the method does not wait for data to arrive.

receiveImmediateDescriptor: [MC_]RECEIVE_IMMEDIATE

Receives data and status information from the partner TP using the specified descriptor. If no data is available, the method does not wait for data to arrive.

requestToSend [MC_]REQUEST_TO_SEND

Notifies the partner TP that the local TP wants to send data.

sendData: [MC_]SEND_DATA

Puts data in the local LU’s send buffer.

sendData:descriptor: [MC_]SEND_DATA

Puts data in the local LU’s send buffer using the specified descriptor.

sendError [MC_]SEND_ERROR

Replies to the [MC_]CONFIRM verb from the partner TP to indicate that an error has been detected.

start TP_STARTED

Notifies APPC that the TP is starting.

stop TP_ENDED

Notifies APPC that the TP is ending.

testRTS MC_]TEST_RTS

Determines whether the partner TP issued the [MC_]REQUEST_TO_SEND verb.

For more information on descriptors, see “Using descriptors to convert data” on page 98.


Using compound verbs You can create a higher-level interface or a custom interface by writing your own methods that combine several APPC verbs. For example, you could write a method called verify: to verify a specific value. To create the method, write appc verify: value. Include the sendData: method to send the value to the partner TP. Add the receiveData method to receive a reply.

Include as many messages as necessary in your compound APPC verb methods to implement your functionality. One compound verb method can even include others. For example, you could include the verify: method in a verifyScreen: method.

Communications User’s Guide, P40-3802 91 Chapter: 3. APPC support Section: APPC implementation

APPC implementation To use ObjectStudio’s APPC implementation, you must first configure an APPC object, as described in the following sections.

Configuration Use the following statement to create an APPC object in your application:

appc := APPC new.

Use the same APPC variable throughout the conversation. Instance variables of the APPC object maintain the parameters required to initialize an APPC conversation. The following table lists the instance variables for APPC objects:

Variable Description

LuAlias Local Logical Unit Alias

PluAlias Partner Logical Unit Alias

tpName Local Transaction Program Name

RemoteTPName Partner Transaction Program Name

ModeName Conversation Mode Name

conversationType Conversation Type

SyncLevel Synchronization Level

useSpecialTable Use the Communications Manager™ alternate “G” table rather than the standard “AE” table for ASCII-to-EBCDIC conversions.

Security Conversation Security Type

UserID Conversation Security User ID

Password Conversation Security Password

The following table lists other instance variables used internally by the system:

Variable Description

tpID Transaction Program ID

convID Conversation ID

ControlBlock Used to issue all APPC verbs

ReportErrors Determines how errors are reported

conversationState Current state of the APPC conversation

DataDescriptor Default global descriptor object used by APPC data methods


The following table lists the methods required to define the client TP:

Method Description

setLUAliasTo: LU alias to use with the method

setPLUAliasTo: PLU alias to use with the method

setModeNameTo: Transmission mode to use with the method

setSyncLevelTo: Sync level to use with the method—the two possible arguments are #None and #Confirm.

setConversationTypeTo: Conversation type to use with the method—the two possible arguments are #Basic and #Mapped.

setTPNameTo: Name of the client TP—takes a string argument that specifies the name of the TP. The TP name is required only for informational purposes and does not correspond to any profile.

setRemoteTPNameTo: Name of the acceptor TP—takes a string argument corresponding to the TP name for the remote TP when setting up the Communications Manager on the accepting side.

setSecurityTo: Optional method that may contain three possible arguments: #None, #Same, and #PGM. The default is #None; any other choice requires you to set the user ID (using setUserIDTo:) and password (using setPasswordTo:), respectively.

setReturnStatusTo: Optional method that returns the conversation status with any data—the two possible arguments are true and false; the default is false.

The setLUAliasTo:, setPLUAliasTo:, and setModeNameTo: methods take string arguments corresponding to profile names created when you set up Communications Manager on the initiating side.

Chapter: 3. APPC support Section: APPC implementation


The following example shows one way to configure a client TP.

appc setLUAliasTo: 'LU'.

appc setPLUAliasTo: 'PLU'.

appc setModeNameTo: 'BLANK'.

appc setSyncLevelTo: #Confirmed.

appc setConversationTypeTo: #Mapped.

appc setTPNameTo: 'CLIENT'.

appc setRemoteTPNameTo: 'SERVER'.

appc setSecurityTo: #PGM.

appc setUserIDTo: 'USERID'.

appc setPasswordTo: 'PASSWORD'.

Conversation sequence The conversation sequence follows these stages:

1. The client TP uses the start method to instruct APPC to start the initiating TP.

2. The client TP allocates a conversation using the allocate method.


3. The client TP may then send and receive data using the following methods:

♦ confirmed

♦ conversationType

♦ flush

♦ getAttributes

♦ prepareToReceive

♦ receiveAndPost:

♦ receiveAndPost:descriptor:

♦ receiveData

♦ receiveDataDescriptor:

♦ receiveImmediate

♦ requestToSend

♦ sendData:

♦ sendData:descriptor:

♦ sendError

♦ testRTS

♦ receiveImmediateDescriptor:

4. When finished, the client TP uses the deallocate method to end the conversation; then it ends the transaction with the stop method.


Determining the conversation state The APPC protocol uses verbs to describe actions within a conversation. Verbs must be issued according to proper APPC protocol. The current state of the conversation determines which verbs may be issued by which TP.

The table and its accompanying numeric key describe which method may be executed when, and the resulting state.

Key Method

- method may not be executed in this state

1 #Reset

2 #Send

3 #Receive

4 #PendingPost

5 #Confirm

6 #ConfirmSend

7 #ConfirmDeallocate

, sequential states; used only by receiveAndPost: methods


To use this table, find the initial state of your system by referring to the key. Then scan the table to find the appropriate method name and its result. For example, if the initial state is 1, #Reset, the allocate method leaves the system in state 2, #Send. If the initial state is 2, #Send, the receiveAndPost: method could leave the system in state 3, #Receive, or state 4, #PendingPost.

Method name 1 2 3 4 5 6 7

Allocate 2 - - - - - -

Confirm - 2 - - - - -

Confirmed - - - - 3 2 1

conversationType - 2 3 4 5 6 7

Deallocate - 1 - - - - -

Flush - 2 - - - - -

GetAttributes - 2 3 4 5 6 7

prepareToReceive - 3 - - - - -

receiveAllocate 3 - - - - - -

receiveAndPost: - 4,3

4,3

- - - -

receiveAndPost:descriptor: - 4,3

4,3

- - - -

receiveData - 3 3 - - - -

receiveDataDescriptor: - 3 3 - - - -

receiveImmediate - - 3 - - - -

receiveImmediateDescriptor: - - 3 - - - -

requestToSend - - 3 - 5 6 -

sendData: - 2 - - - - -

sendData:descriptor: - 2 - - - - -

sendError - 2 2 2 2 2 2

start 1 - - - - - -

stop 1 1 1 1 1 1 1

testRTS - 2 3 4 5 6 7

All receive methods can result in #Confirm, #ConfirmSend, and #ConfirmDeallocate if you specify the #Confirm sync level. If the partner TP terminates abnormally, the receive methods can result in #Reset. However, if you have a reliable link, use the #None sync level to reduce the number of methods in your applications (such as the confirm and confirmed methods).


Using the receiveAndPost: method To make a request that may take some time to process, use the receiveAndPost: method. Because it executes and receives data asynchronously, this method makes your applications more responsive to users. While waiting for the response, ObjectStudio continues to execute your application.

The receiveAndPost: method has a two-part response. The first part only confirms that a message was sent (posted). The second part of the response consists of a one-argument block, called when the request is processed. The argument to this block indicates one of three possibilities:

♦ An error with an error message object

♦ A status change with the APPC object

♦ Data transfer

The following code shows an example of the receiveAndPost: method:

APPCObj receiveAndPost: [:result|

(result isKindOf: APPCError)

| (result isKindOf; Message) ifTrue: [

'an error has occurred' out.

^self.

].

(result == APPCObj) ifTrue: [

'status change only, no date' out.

^self

].

'data was received' out.

result out.

].


Creating an APPC server To turn a controller into an APPC server, make it a subclass of APPCServerController and write a start method. Then use the program generator to create an application image file. When APPC invokes your application, your controller opens and the start method executes.

Using descriptors to convert data To convert data easily, write both TPs in Smalltalk. Then you can send and receive Strings, Symbols, SmallIntegers, LongIntegers, Float and Character objects, and nil.

To communicate with a TP that was not written in Smalltalk, you must use descriptors. Simple descriptors define a single data buffer. Complex descriptors contain several simple descriptors as arrays of data objects and are best used to transfer large amounts of data. To improve the performance of your applications, use complex descriptors to process as much data as possible per transaction.

The Descriptor class allows you to describe data buffers to be transferred between TPs. Use the following statements to define your descriptors:

♦ To create an instance of class Descriptor for your APPC application:

descriptor := Descriptor new.

♦ To define a name for a descriptor object and make it globally available:

descriptor := Descriptor newName: #Descriptor1.

♦ To retrieve the descriptor from anywhere in the system:

descriptor := Descriptor getNamed: #Descriptor1.

♦ To define a default descriptor for data that you transfer frequently:

setDataDescriptorTo:


Instance variables A Descriptor object uses the following instance variables:


Name Optional name for the descriptor

bufferType Type of data in the APPC data buffer

atomType Class of object that the data represents in ObjectStudio

conversions Conversions to be performed on the APPC data buffer

size Field size in the APPC data buffer

Types The following table lists possible buffer, atom, and conversion types:

Type Includes

buffer #Char, #VarChar, #Short, #Long, #Float, and #Double where: #Char is a fixed-length string with no terminating null character, and #VarChar is a variable length string with a terminating null character

atom #String, #Symbol, #SmallInteger, #LongInteger, and #Float where: #String and #Symbol atom types use only the #Char and #VarChar buffer types, and #SmallInteger, #LongInteger, and #Float atom types use the #Short, #Long, #Float, and #Double buffer types.

conversion #ByteFlip, #EBCDIC, or an array that specifies one or more conversions where: The #ByteFlip conversion sets the APPC buffer to byte flip number fields, and The #EBCDIC conversion type defines the APPC buffer as an EBCDIC #Char or an EBCDIC #VarChar field. Conversions between ASCII and EBCDIC use a default conversion table; set the setSpecialTableTo: method to true to instruct the Communications Manager to use the alternate conversion table.


Example of a simple descriptor The following example defines a simple descriptor:

descriptor setBufferTypeTo: #Char.

descriptor setAtomTypeTo: #String.

descriptor setSizeTo: 40.

descriptor setConversionsTo: #EBCDIC.

Modifying the translation module With ObjectStudio, you have access to the C source code for the translation module that handles data conversion. With the addition of a C compiler and a make facility, you can easily add buffer types, atom types, and conversions to customize your applications. This section describes the conversion process.

ObjectStudio to ObjectStudio To add another object to transfer between two ObjectStudio TPs, modify the EncodeData and DecodeData functions. For the EncodeData function:

1. Add another case statement for the new class of object.

2. Add a new data type identifier (DT_*), and assign the next available ordinal number.

3. Add a case statement to the DecodeData function to recognize the new data-type identifier.

4. Create a new object of the appropriate class.


ObjectStudio and another TP To transfer data between ObjectStudio and another TP, you need to create descriptors, as described in “Using descriptors to convert data” on page 98. To add atom types, buffer types, and conversions specified by descriptor objects, modify the EncodeItem, DecodeItem, and PerformConversions functions.

For any new function:

1. Add a symbol object identifier.

2. Add the symbol string to the apszSymbols array.

3. Add the offset identifier (idx*).

Remember to increase the idxLast identifier value as needed.

For the EncodeItem and DecodeItem functions, add an if statement for any new atom type or buffer type.

For the PerformConversions function, add an if statement for any new conversion. The system supplies the correct conversion direction.

Handling errors By default, ObjectStudio handles errors for you. If an error occurs, the Debug Interface dialog box displays the error and gives you the option to resume or abort. To handle the errors yourself, especially in the case of an unattended APPC server, use the doNotReportErrors method. To return error handling to ObjectStudio, use the reportErrors method.

Chapter: 3. APPC support Section: APPC implementation

Communications ’s Guide, P40-3802 102

Tutorial example This section contains a sample APPC application. Review this example when planning your own APPC applications. The example will run correctly if both your client and server Transaction Programs (TPs) use ObjectStudio. However, if the remote system does not use ObjectStudio, you must insert the correct communication configurations for your system. When changing the communication parameters, pay particular attention to the following information:

♦ Logical Unit Alias Name

♦ Partner Logical Unit Alias Name

♦ Transaction Mode Name

Modifying the tutorial files To modify the tutorial files to suit your own applications:

1. Create a TP profile on the server machine. For information on Transaction Program profiles, see “APPC overview” on page 85.

The TP profile must execute ostudio.exe and pass the image name that will be created as a parameter in the profile.

2. Supply the full pathname for ostudio.exe in the TP file’s specification field.

The TP Name field is case-sensitive, so enter the information carefully. The APPC examples must use the correct TP name to match the Transaction Program profile.

3. Set the TP Parameters field to:

UserChapter: 3. A rt Section: Tutorial example

PPC suppo

-ifullpath\image.img.

where:

fullpath is the location of the server application image.

image is the name of the server image file to be created.

Normally, when executing ObjectStudio, the parameter -iostudio.img loads the default distributed image.

Communications User’s Guide, P40-3802 103 Chapter: 3. APPC support Section: Tutorial example

Building the server TP image This example shows how to change the current state of the APPC conversation (from send to receive) and how the remote application receives data.

To implement this example, you must first build the Server image and configure the Requester image.

To build the Server TP image:

1. Modify the file appcsx1.cls on the server machine to reflect the configuration of the communications software.

2. Modify the finishInit method to set the TP Name to the name specified in the configured TP Profile.

3. Start ObjectStudio.

4. Select File ⇒ Load application.

5. Select APPC and click Load.

6. Click Close after the application loads.

7. Select File ⇒ Load file.

8. Select appc\appcsx1.cls and press ENTER or click OK.

9. Create a new program:

A. Select Tools ⇒ Program Generator.

The Program Generator opens.

B. Select APPC Server Example 1 from the Applications Controller list as the controller name.

C. Click OK to generate the new image file.

10. Enter the name of the image file that matches the TP Parameter field in the TP profile. This name must have the same path and image name as specified in the created profile.

11. Ignore the errors that result and exit ObjectStudio.


Configuring the requester To configure the Requester:

1. Modify the file appcrx1.cls on the server machine to reflect the configuration of the communications software.

You will probably change the LU alias, the PLU alias, and the remote TP name. The mode name is an IBM default and the requester’s TP name is not used.


3. Select File ⇒ Load application.

4. Select APPC and click Load.

5. Click Close after the application loads.

6. Select File ⇒ Load file to open the File Open dialog box.

7. Select appc\appcrx1.cls and press ENTER or click OK.

8. Double-click the new interface icon to open the controller.

You have established a session with the remote machine, but you have not yet allocated a conversation. To allocate a conversation, you must flush the queued message buffer. The message buffer contains the allocation request along with other messages to be sent to the remote application. You can flush this buffer explicitly by sending a flush method to the APPC object. However, the system flushes the buffer implicitly whenever the state changes in the current APPC conversation.

The example under Tutorial procedure relies on implicit flushes of the message buffer.

Chapter: 3. APPC support Section: Tutorial example


Tutorial procedure The server and requester applications are identical. Both applications can issue send, receive, and deallocate messages, but only the application in the send state can transmit data or terminate a conversation. Consequently, the Send and Exit buttons are enabled only on the application in the send state.

1. Allocate the conversation and initialize the remote TP.

2. Click Receive on the requester application to change the state of the conversation and flush the message buffer. (The buffer contains the allocation request.)

The remote TP initializes and activates the server ObjectStudio APPC application. While the server application is in the send state, you can transmit an unlimited number of send requests. You can change the values in the send buffer at any time. The program queues each request until you change the state of the server application by clicking Receive or Exit.

The requester application remains in the pending-post state until it receives all messages and the state change notification. Similarly, the server application remains in the pending-post state until it receives a state change from the requester application.

3. Click Send twice; then click Receive on the server application. (Clicking Receive establishes the change of state from send to receive.)

4. Click Receive twice on the requester application to receive each message from the server application and update the received fields.

5. Click Receive a third time on the requester application to receive the state-change notification from the server application. The requester application becomes the server, so its Send and Exit buttons are activated.

6. Repeat this example as needed to see how APPC conversations are actually performed.

You must transmit an extra receive request to change the state of the conversation. Examine this example closely to identify the actions needed to detect APPC conversation changes in a posted receive routine.

7. Click Exit on the current server application. The server application terminates and exits ObjectStudio.

Chapter: 3. APPC support Section: Tutorial example


4. TCP/IP support Overview

ObjectStudio includes networking via TCP/IP. To use ObjectStudio TCP/IP support, load the TCP/IP loadable application.

ObjectStudio has a Socket class, and implements the TCP/IP socket Application Programming Interface (API). The Socket class and the socket API make protocol suites available, including tcp (Transmission Control Protocol) and the connectionless udp (User Datagram Protocol).

Before reading this section, you should be familiar with network programming.

Network communication You can think of network communication as a conversation between two partners. One partner takes the role of the client, and the other takes the role of the server. The client and server establish the conversation by creating sockets, which are the conversation endpoints.

Chapter: 4. TCP/IP support Section: Overview

Communications User’s Guide, P40-3802 107 Chapter: 4. TCP/IP support Section: Overview

Types of conversations The types of conversations are:

♦ Connection-oriented conversation. Requires that the system establish a connection before the conversation takes place. The sequence in which messages arrive is guaranteed to be the same as the sequence in which they are sent. A typical example of a connection-oriented conversation is the telnet service.

♦ Connectionless conversation. Requires that each message contains the information required for its delivery. The sequence in which messages arrive can be different from the sequence in which they are sent. A typical example of a connectionless conversation is the rwho service, which sends information about local users to remote machines.

ObjectStudio implementation In ObjectStudio, a socket is represented by an object of class Socket. Each socket is associated with an address, implemented as an object of type SocketAddress. Finally, objects of class Descriptor interpret and structure the data that is transferred during the networking conversation.

Communications User’s Guide, P40-3802 108 Chapter: 4. TCP/IP support Section: SocketAddress class

SocketAddress class An object of class SocketAddress represents a network address. This class consists of three components:

♦ Host name

♦ Service name

♦ Protocol name

Creating a SocketAddress To create an object of class SocketAddress, send the host:service:proto: message to a subclass of class SocketAddress.

Host parameter The host parameter is a host name specified in one of two ways:

♦ In the form hostname@domain.

♦ In the address format with the appropriate notation for the protocol family. For example, you can specify an internet address using the dotted address notation, such as 132.147.143.12.

Service parameter The service parameter is the name of a service listed in /etc/services. This parameter does not apply for UNIX Domain addresses.

Communications User’s Guide, P40-3802 109 Chapter: 4. TCP/IP support Section: Creating a socket

Proto parameter The proto parameter is a Symbol indicating the protocol to use. Instead of the name of an existing service, you may use a string representation of a service port number. The following table lists the symbols you can use for the proto parameter:

Protocol family

Connection-oriented conversation

Connectionless conversation

Internet #tcp #udp

XEROX® NS #spp #ip

Example of creating a SocketAddress This example shows you how to create a SocketAddress for a client Internet stream socket. The client will connect to the telnet service on your local machine. The following code creates the SocketAddress:

address := InetAddress host: 'localhost'

service: 'telnet'

proto: #tcp.

Creating a socket To create a Socket object, send the newFor: message to class Socket. The newFor: method determines the address of the connection, the protocol family, and the protocol type for the socket.

Address parameter. The parameter to newFor: is a socket address, an object that is a subclass of class SocketAddress. The following table describes the address objects that can serve as a parameter to the newFor: method:

Address object Description

InetAddress An address in the Internet protocol family.

NSAddress An address in the XEROX NS protocol family.

Communications User’s Guide, P40-3802 110 Chapter: 4. TCP/IP support Section: Working with sockets

Working with sockets To work with sockets, you establish a communication protocol. The protocol varies, depending on:

♦ Whether the message-sending object is a client partner or a server partner in the conversation

♦ Whether the conversation is connection-oriented or connectionless

The following topics show a suggested abstract sequence of calls issued by a connection-oriented server and client. There is also an example of code for a connection-oriented client.

Connection-oriented server The following table represents an abstract sequence of calls issued by a connection-oriented server:

Message Description

newFor: Creates a socket endpoint for an incoming connection.

Bind Binds a local network address to the socket.

listen Indicates that the server is ready to receive connections.

accept Accepts an incoming connection from a client. If the operation is successful, it creates the connection point, an instance of class Socket.

setDataDescriptorTo: * Specifies the structure of data that is sent over the connection.

receiveData sendData

Transfers data using receive and send.

Close Ends the conversation.

* This call is specific to the ObjectStudio TCP/IP implementation and is not mandatory in the TCP/IP API.

Communications User’s Guide, P40-3802 111 Chapter: 4. TCP/IP support Section: Working with sockets

Connection-oriented client The following represents an abstract sequence of calls issued by a connection-oriented client:

Message Description

newFor: Creates a socket.

connect Connects to an existing service.

setDataDescriptorTo: * Specifies the structure of data that is sent over the connection.

receiveData sendData

Transfers data using receive and send.

Close Ends the conversation.

* This call is specific to the ObjectStudio TCP/IP implementation and is not mandatory in the TCP/IP API.

Example. The following example presents code that implements a connection-oriented client. The client sends a string to a server. The server interprets the string as a number and echoes a string containing the square of the number. In order for this example to work, list the name of the server in /etc/services.

socket := Socket newFor: (InetAddress host: '127.0.0.1' service: 'square' proto: #tcp).

socket connect.

socket setDataDescriptorTo: (Descriptor getNamed: #String).

socket sendData: '40'.

socket receiveData out.

-> '1600'.

socket close.

In this example, 127.0.0.1 is the address of the local host; its use shows you how to provide dotted notation for the host address. For more information about the Descriptor class, see “Descriptor class” on page 113.


Advanced socket operations

Receiving data of arbitrary length ObjectStudio has a TCP/IP read limit of 4200 bytes. As a result, you cannot read more than 4200 bytes of network data in a single chunk, without performing the steps in this section.

To read more than 4200 bytes of network data in a single chunk, perform the following:

1. Change the last line of Socket>>privateReceive to the following:

...

^result "return the ByteArray here, not the decoded object"

An alternative to step 1 is to create a copy of the privateReceive method in the Socket class, with a new name. Replace the last line of this method with the following:

^result

This method could be named, for example, “privateReceiveUnlimitedBytes.” You would then call this new method from your application, in a loop such as the one shown in step 2.

2. In the application controller method, use a loop to receive the network data. See the following example:

tcpipInputAvailableFor: aForm

| data result dataObject |

data := ByteArray new.

[server readyForRead]

whileTrue: [ result := server receiveData.

result notNil

ifTrue: [data := data addAll: result]].

data isEmpty

ifTrue: [ self displayStatus: 'Client hung up'.

server close.

^ server := nil].

dataObject := data decodeUsingDescriptor: nil.

...

Chapter: 4. TCP/IP support Section: Advanced socket operations


Setting a timeout During the send and receive part of a conversation, the conversation may be blocked. For example, the conversation partner may be out of order or loaded too heavily. You can declare a timeout limit by sending the setTimeout: message. The setTimeout: message sets a limit, in milliseconds, on the amount of time that a conversation partner will wait for a response. Use the setTimeout: message in conjunction with the readyForRead and readyForWrite messages to determine whether a connection is still active.

Setting operation mode You can set parameters that determine a socket’s operation mode. To set the operation mode, send the privateSetOption:value: message. To get the value of the operation mode, send the privateGetOption message. For a detailed list of socket operation modes, see the documentation about your socket’s API implementation.

Descriptor class The Descriptor class describes the data buffers that are transferred between conversation partners during a network conversation.

You create a Descriptor by sending the new message to Descriptor. Once you create a Descriptor, register it by sending the newName: message.

You can use an array to store Descriptors of data buffers that contain more than one field.

The implementation of the Descriptor class for TCP/IP is nearly identical to its implementation for the ObjectStudio APPC loadable application. For more information, see “APPC overview” on page 85.

Chapter: 4. TCP/IP support Section: Descriptor class

Communications User’s Guide, P40-3802 114 Chapter: 4. TCP/IP support Section: Descriptor class

Instance variables The instance variables of a Descriptor object determine how ObjectStudio converts data into objects and how it converts objects into data. The following table describes the instance variables of a Descriptor:


Name The name of the Descriptor.

atomType A symbol representing the type of object that the conversation partner sent or received; one of: #String, #Symbol, #SmallInteger, #LongInteger, #Float.

bufferType A symbol representing the data type of the exchange buffer; one of: #Char, #VarChar, #Short, #Long, #Float, #Double.

Conversions Not used for TCP/IP because the system handles conversions between integer data-types. Specify a value of nil.

Size The maximum length in bytes of the send or receive buffer.

ObjectStudio provides methods to set and get each instance variable.

Example. The following example sets some of the instance variables of a Descriptor that has already been created:

descriptor := Descriptor newName: #String.

descriptor setAtomTypeTo: #String.

descriptor setBufferTypeTo: varChar.

descriptor setSizeTo: 32.

The following comments apply to the lines of code:

Registers a Descriptor with a name of String.

Declares that passed objects are Smalltalk strings.

Declares that the buffer has an arbitrary length byte array and that there are no byte conversions for it.

Declares the maximum length for the send buffer.

Communications User’s Guide, P40-3802 115 Chapter: 4. TCP/IP support Section: Asynchronous data transfer

Asynchronous data transfer In the TCP/IP interface, ObjectStudio provides a notification mechanism that allows you to:

♦ Make an asynchronous connection

♦ Wait for an asynchronous connection

♦ Transfer data asynchronously

Overview The notification mechanism informs the application about an incoming event on a socket. To work with notifications:

1. Register an object of class Form by sending the registeredEventOn: message. The parameter is the form object.

2. Send the notification to the form object by sending the tcpipInputAvailableFor: message to its controller.

3. In the controller, implement the method tcpipInputAvailableFor: to handle the notification.

4. Once the form is notified, the notification mechanism disconnects and you have to register the notification handler for the next transaction.

Communications User’s Guide, P40-3802 116 Chapter: 4. TCP/IP support Section: Asynchronous data transfer

Asynchronous data transfer example The code shown below:

♦ Sends an object to a remote connection

♦ Registers an event handler

♦ Waits asynchronously for a reply

socket sendData: anObject.

socket registerEventOn: self mainForm.

The following code is an implementation of the method tcpipInputAvailableFor:. This method is implemented in the application controller. It is called when the other side of the conversation sends a reply and reads the reply.

tcpipInputAvailableFor: aForm

socket setTimeout: 2000.

socket readyForRead ifFalse: [

" do error handling for timeout here"

].

" get reply "

reply := socket receiveData.

...

Communications User’s Guide, P40-3802 117 Chapter: 5. DDE support Section: Overview of Dynamic Data Exchange

5. DDE support Overview of Dynamic Data Exchange

Dynamic Data Exchange (DDE) is a Microsoft Windows protocol that allows different applications, operating on the same machine, to exchange data or commands. The DDE protocol defines messages that control the synchronization of data exchange. DDE ties the data in an application to its source. When the source data changes, data in the application is updated via the link.

Client/server conversation The basic conceptual model for a DDE connection is a conversation. A DDE participant can be a client or a server. The client initiates a conversation and controls the flow of the conversation. The server responds to an initiation and responds to requests from the client.

The client does any or all of the following:

♦ Issues one or more requests for data from a server.

♦ Sends unsolicited data to a server.

♦ Asks a server to execute commands.

♦ Establishes an advise state (also known as a hot link) with a server. An advise state is one where the client receives notification (and possibly data) from the server each time specific data is modified.

Each individual data exchange within a conversation has an associated item name and format. These are established at the time the data is requested, and can be any name and format on which the two applications agree.

The protocol hierarchy contains provisions that allow the server to reject requests. Several requests for the same data may be required before the two partners agree on a data format that both can handle. Either partner can terminate the conversation at any time.

Although a single conversation involves only two participants, an individual application can carry on multiple conversations with one or more partner applications, presenting itself as a client, a server, or both.


DDE protocol hierarchy DDE uses the following three-level hierarchy to identify a data unit required by a DDE client:

Level Description

Application The name of a server that controls some common data; for example, Excel or myDDEServer.

Topic The data context; for example, a file name or application specific string, such as the name of a database.

Item The data object passed into a DDE transaction; for example an integer, a string, or a database table. When a client issues a request for an item specifying its item name, it receives the contents of this item from the server application.

The DDE client can communicate with another application in several topics at the same time, but it must start a new session for each topic.

Starting a DDE conversation The DDE conversation starts with the following steps:

1. The client application initiates the DDE conversation and attaches itself to the server.

2. The client specifies the application name and the topic name.

3. When a server receives the initiate request, it examines the application name and the topic name to see if it matches its own.

4. If the application and topic name match, the server sends an acknowledgment.

5. The client can then continue.


Holding a DDE conversation After you establish a conversation between a server and client, the client application can request other types of transactions. Each of these transactions must specify an item that can be correctly identified by the DDE server application. The following table identifies the possible transactions:

Transaction Description

initiate Begins a conversation with another application.

request Returns the value of a particular item from the server. Sent by the client to get information from the server.

advise Establishes a hot link between the client and the server, whereby the server must notify the client whenever the value of the data changes.

unadvise Disables all links for a specified exchange.

poke Sends data to the server to change the value of a particular item.

execute Executes commands in other applications. Sends a string from the client to the server. In ObjectStudio, the server expects the string to be source code that it can compile and execute.

terminate Stops a given exchange. Both the client and the server application can issue a terminate message to the other application. All transactions must be completed or ended before this message can be sent. If the client has issued an advise message, it must send an unadvise message before terminating the conversation.

Communications User’s Guide, P40-3802 120 Chapter: 5. DDE support Section: Using DDE

Using DDE ObjectStudio provides two classes to implement the DDE protocol:

♦ DDEClientSession

♦ DDEServerSession

These classes maintain the low-level information required by the DDE protocol and provide a set of methods that simplify DDE application development.

The methods implement all available DDE functions so you can develop both server and client applications. Client applications can communicate with any server, and server applications provide access to information from any DDE client. ObjectStudio hides all of the implementation details to ease DDE application development.

For detailed information about each DDE method, use the online method reference.

Enabling ObjectStudio DDE support Enable DDE support in ObjectStudio by selecting DDE from the Applications dialog box.

Creating a DDE server session Be consistent when you develop DDE server applications so that DDE client applications can communicate easily with them. The name of the DDE server application and the list of available topics must be available to the DDE client.

Provide documentation with DDE server applications that lists the DDE application name, the available topics, and the items supported by the topics. This information allows DDE client applications to interface with the DDE server application. We also recommend that you support the ‘System’ topic as described in the IBM Presentation Manager Programmer’s Reference, Volume 1. This topic provides information that other DDE client applications can use.


Registering the server To register your application as a server and define the list specifying to which topics the server will respond, send the following instance method from class Form to the main form of your controller:

setDDEApplication:appname topics:topicList

where:

♦ appname is a string or symbol defining the name of the DDE Server application (not necessarily the name of the controller).

♦ topicList is an array of all topics in the DDE server application.

For example, the application MyDDEServer has a topic list of Employees, Products, and System. It is implemented in the openInitialization method of the controller, as shown here:

openInitialization

| topicList |

topicList := Array new.

topicList add: #Employees.

topicList add: #Products.

topicList add: #System.

(Self mainForm) SetDDEApplication: MyDDEServer

topics: topicList.

This example assumes that the mainForm of the controller is intended to respond to DDE clients that send an initiate request to MyDDEServer.

ObjectStudio allows a server application to respond simultaneously to different client applications. An ObjectStudio DDE server application will only respond if the application name has been assigned to a top-level form (not a SubForm) and if the form is open.

ObjectStudio allows a DDE server application name to be assigned to any top-level form within the controller. Only one DDE server application name can be assigned to each top-level form, but different DDE server application names can be assigned to individual top-level forms within the same controller.


Defining server response An ObjectStudio DDE server application must implement several instance methods that a client DDE application calls when it successfully initiates a conversation. The methods must respond to the client with either a positive response, a negative response, or the updated value (which implicitly issues a positive response). A DDEServerSession object is passed to each of these methods and must be used for the response.

DDE methods that you must implement are:

requestDDEUpdateFor: itemName using: session Description Called when a client issues a request transaction. If the

itemName is valid, the server DDE application passes the result by sending the updateItem:to: message to the session object.

startDDEUpdateFor: itemName using: session Description Called when a client issues an advise transaction. If itemName

is not valid, this method sends a negativeResponse message to the session object. If itemName is valid for continuous updates, this method sends a positiveResponse message to the session object and also sends the updateItem:to: message. The server application is then responsible for sending the updateItem:to: message to the session object whenever the value of itemName changes.

stopDDEUpdateFor: itemName using: session Description Called when a client issues an unadvise transaction. The server

application sends a postiveResponse message to the session object if itemName was involved in continuous updates. Otherwise, it sends a negativeResponse message to the session object. The DDE server application will no longer send continuous updates for this itemName.


unsolicitedDataDDEEventFor: itemName is: data from: session Description Called when a client issues a poke transaction. The DDE server

application is responsible for changing the value of itemName and sending a positiveResponse message to the session object if itemName is valid. This method assigns data to itemName and is also responsible for checking the type of the data object. It sends a negativeResponse message if itemName is not valid.

executeDDEEventFor: itemName is: command from: session Description Called when a client issues an execute transaction. If

itemName is a valid item that can be used to execute the command, it sends a positiveResponse message to the session object. Otherwise, it issues a negativeResponse message. The command object is passed as a symbol to this method. The server application documents how it expects this command to be composed and can allow passing direct Smalltalk commands. This command could then be executed by the following methods:

block := command asString asStream asBlock.

Block == nil ifTrue: [

^ session negativeResponse.

].”EndIf”

block exec.

session positiveResponse.

The same user-supplied methods are called for each of the individual DDE servers. The session object is passed to each of these methods in order to correctly identify which server has been requested. To simplify the methods, assign only one DDE server application in a controller.

If the DDE server application supports multiple topics, a topic method sent to the DDEServerSession object can determine which topic is requested. An itemName symbol, which the client DDE application has specified in the transaction request, is also passed to each of these methods. To perform the appropriate action, check this itemName object.


Creating a DDE client session The DDEClientSession object allows ObjectStudio DDE client applications to communicate with any active DDE server applications.

A DDE client application must first register itself in an initialization method by creating a DDEClientSession object using the following DDEClientSession class method:

name:name application:application topic:topic item:item

where:

♦ name is the name of the DDE client.

♦ application is the name of the DDEServer, an identifier which is used to check the machine for servers with the same application name.

♦ topic specifies the topic for that session.

♦ item is the initial item name, which defines the conversation point between the client and the server.

Example. For example, if a DDE client application is to exchange data using the Name item of the Employees topic of a DDE server application named myDDEServer, the following method creates a DDEClientSession object called myClient:

clientObject := DDEClientSession name: #myClient

application: #myDDEServer topic: #Employees

item: #Name

The fields specified in this method must match what the DDE server application expects when it is initiated. The DDE client application can then send an initiate method to the DDEClientSession object, which attempts to communicate with any DDE server application.


Defining client response After the client application has registered itself as a DDE client, it must set a named trigger for the callback method from the server application. Send the following message to the client session object:

setActionNamed: name to: block

where:

♦ name is the name of the trigger for the session.

♦ block is a one-argument block and is added to the dependency dictionary of the receiver. The block is automatically executed when DDE messages are sent from the server. Each block checks the conversation status of the DDEClientSession object to determine which type of action to perform.

Example. For example, an initialization method might contain the following code. Here, the block calls the method eventSession, which then checks the status of the DDE session.

client setActionNamed: #action to:

[ :session | self eventSession: session.

].


Checking the status of the DDE session The lastOperation method returns the instance variable that contains the last DDE session operation. Possible return values are:

♦ #Initiate

♦ #Request

♦ #StartUpdate

♦ #StopUpdate

♦ #Terminate

♦ #Set

♦ #Execute

The status method returns an instance variable that contains the status of the DDE conversation. Possible return values are:

♦ #Acknowledged

♦ #Unacknowledged

♦ #NotActive

♦ #Busy

♦ #NotAcknowledged

Use the status method after the initiate method to ensure that a conversation has been established.

The currentValue method returns the last value of the item used for data exchange.

Chapter: 5. DDE support Section: Using DDE


DDE transactions The methods that issue the different DDE client transaction requests to the DDE server application are:

request requestFor: newItem Description Issue a request transaction to the DDE server.

startUpdate startUpdateFor: item Description Issues an advise transaction to the DDE server for the given

item that is stored in the DDEClientSession object.

stopUpdate stopUpdateFor: item Description Issues an unadvise transaction to the DDE server.

setValueTo: newValue setValueFor:newItem to: newValue Description Perform the poke transaction to the DDE server. The newValue

passed to the DDE server is set to the given item.

executeCommand: command executeCommandFor: command Description Passes the command object to the DDE server. This object

should match the protocol that the DDE server can execute.

initiate Description Initiates the conversation with the DDE server.

terminate Description Terminates the conversation with the DDE server.

Communications User’s Guide, P40-3802 128 Chapter: 5. DDE support Section: DDE sample applications

DDE sample applications This section describes some simple DDE examples that demonstrate the methods that must be used for both server and client applications.

The sample includes two ObjectStudio applications: the DDE server application and the DDE client application. The DDE conversation is performed by requests from the client application to the operating system and replies from the server application to the operating system. It is important to note that communication is performed by the operating system and not by the two applications directly. The DDE client application provides an interface to all of the DDE protocol. This sample application could easily be used to interface to other DDE applications.

The ObjectStudio DDE server application defines an application named myDDEServer and provides a topic list consisting of variables. This topic list has support for the items string and number. The items refer to the two entry fields of the main controller. The DDE server application allows both of these fields to be changed and to display any changes that are made by a client application.

The DDE server application also supports the DDE execute request from a client application. This application expects the command to be a block of ObjectStudio code that can be compiled and executed. It also has an Update button that allows the user to manually send updates to DDE client applications.

Update requests are stored in an array of dictionaries in the DDE server application. This array is checked whenever the user clicks Update. Entries in this array are removed whenever a stop update request is received by the DDE server applications. The logic used in this application can be used in other DDE server applications that support update requests.


Starting the server and client applications

Loading the server To load the files for the DDE server:


2. Open the Desktop pop-up menu, and select Load file.

3. Select and load the file demo\dde.

4. Double-click the DDEServer icon on the Workplace Desktop to open the Server application.

Loading the client To load the files for the DDE client:

1. Start a second copy of ObjectStudio.

2. Open the Desktop pop-up menu, and select Load file.

3. Select and load the file tutorial\ddecl.cls.

4. Double-click the DDEClient icon on the Workplace Desktop to open the Client application.

At this point, both server and client applications should be open on the screen. The following section describes how to initiate the conversation so you can perform other DDE commands.


Initiating the conversation To begin a conversation:

1. Select the DDEClient window.

2. Type the following into the Application field:

DDEServer

3. Type the following into the Topic field:

Variables

4. Click Initiate to initiate the DDE conversation.

The system updates the Status field to Acknowledged and the Last Operation field to Initiate

Performing a request To perform a request:

1. Select the DDEServer window.

2. Type the day of the week in the String entry field.

3. Type a number into the Number entry field.

4. Select the DDEClient window.

5. Type the following into the Item field:

string

6. Click Request.

The value of the string field (the day of the week) in the DDEServer application appears in the Current value field of the DDEClient application.

7. To retrieve the value from the number field of the DDEServer window, type number in the Item field of the DDEClient window and click Request.


Setting values To set the value for the DDEServer by entering a value from the DDEClient:

1. Type your name in the Current value field of the DDE client.

2. Type the following in the Item field:

string

3. Click Set Value.

The text you typed into the Current value field appears in the String field of the DDEServer application.

4. To set the numeric field value of the DDEServer, enter a number in the Current value field of the DDEClient application, set the Item field to number, and click Set Value.

Updating the client To send updated values to any DDE client application that requests them:

1. Enter the following in the Item field of the DDE client:

string

2. Click Start Update.

The Stop Update button is enabled, and the Start Update button is disabled.

3. Enter a new string in the String field of the DDE server.

4. Click Update.

The new value of the string appears in the Current value field of the DDEClient window. The new value of the string is transmitted to any DDEClient application that has requested updates.

5. Click Stop Update in the DDEClient window to stop the transmission of updates from the server application to the client application.

6. Repeat steps 1–5 for the number field.


Executing commands To use the Execute conversation type that allows a command to be sent and executed on the DDE server:

1. Type the following in the Item field of the DDE client:

string

2. Type the following in the Current value field:

DDEServer openSubForm

3. Click Execute.

The DDEServer application executes the command you entered in the Current value field of the DDEClient application and displays a subform of the DDE server application.

4. Type the following in the Current value field of the DDE client:

DDEServer closeSubForm

5. Click Execute.

The DDE server closes the subform window.

Ending a conversation To terminate the conversation between the DDE client and server applications:

1. Select the DDEClient Window.

2. Click Execute to terminate the DDE conversation.

Communications User’s Guide, P40-3802 133 Chapter: 6. Opentalk Communication Layer Section: Introduction to the ObjectStudio Opentalk Communication Layer

6. Opentalk Communication Layer Introduction to the ObjectStudio Opentalk Communication Layer

Opentalk background Opentalk is a VisualWorks® add-on that provides an environment for the development, deployment, and maintenance of distributed applications.

The Opentalk Communication Layer consists of those components that define the base communication framework, the Smalltalk-to-Smalltalk communication protocols, and a select set of base services. It is that part of Opentalk targeted first toward the needs of protocol developers, and second toward the needs of distributed service, component, and application developers planning to build directly off the communication layer.

Port of the Opentalk Communication Layer to ObjectStudio The port of the Opentalk Communication Layer to ObjectStudio is intended to provide ObjectStudio developers with a Smalltalk-specific protocol for communication with other ObjectStudio and VisualWorks images over TCP/IP. The port allows users of any one Cincom Smalltalk product to take advantage of many of the services and capabilities specific to the other.

ObjectStudio Opentalk Communication Layer documentation For documentation on the ObjectStudio Opentalk Communication Layer, refer to Opentalk Communication Layer, P40-3806. This document is partly derived from the practical introduction to Opentalk presented in Chapter 2 of the VisualWorks Opentalk Communication Layer Developer’s Guide, P46-0135.

A more extensive, but less directly applicable, introduction to Opentalk is provided by the VisualWorks Opentalk Communication Layer Developer’s Guide, P46-0135. This document discusses the fundamental concepts behind Opentalk in its third chapter, discusses some aspects of the design of Opentalk in its fourth chapter, and provides guidelines for distributed application development its fifth chapter.

Communications User’s Guide, P40-3802 134 Index

Index 3

3270 and 5250, differences in implementation 68

5

5250, unsupported methods 68

A

accepting conversations 86 accessScreen method 40 activateEmulator method 38 active conversations 113 adding fields 17 addresses, network 108 advise state 117 advise transaction 119

example 128 server response to 123

allocate 88, 93 API, TCP/IP 106 APPC

class 88 methods. See methods object

configuring 91 creating 91 instance variables 91 status change 97

sample application 102 server 98

application 118 array elements 72 asynchronous connection 115 at:fieldName method 38 at:fieldName put:text method

38 at:label method 36 Attachmate EXTRA! 44 automating repetitive tasks 42 availability of host 57, 76

B

Browser, Loadable Applications 10

buffer data buffers 113

Build Interface 24 icon 25 starting 25

buildErrorMessage:msg number:num 38

building server TP image 103 buttons

PF 26, 28, 32 Send Data 28

C

changePMWindowStatus:x:y:dx:dy:behind: 77

changePMWindowStatusFlags:x:y:dx:dy:behind: 54

changePSWindowNameTo: 54, 68

changeSwitchListLTNameTo: 54, 68

changeTo:screen method 38 changing

communication parameters 102

conversation state example 103 prepareToReceive

method and 88 screens 54 status of emulator window

54 checkCurrentScreen method

40 checkPSFor: 60 class CommController 40 class EHLLAPI. See EHLLAPI

class.


class methods EHLLAPI 50 Host Screen, screens 36

class variables 49 commDLLName 49 getEAB 49 xlate 49

classes APPC class 88 Descriptor 107, 113 Socket 107 SocketAddress 108

client connection-oriented 111 creating DDE client session

123 linking to server 118, 122,

124 methods 120 network communication and

106 sample application 128 TP, defining

example 93 close method 40 closing

emulator session, trapping 65

Host Screen Editor 20 codePage

instance variable 49 method 55

commands, executing 119, 123 CommBuilder

classes 35 development cycle 11 icons 11, 22 introduction 8 loading 11 methods 28, 35 pop-up menu 21 prerequisites 9 session icons 12 starting 9 template objects 12 workplace 21, 22

CommController class 40 methods

accessScreen 40 checkCurrentScreen 40 close 40 EHLLErrorDisplay 40 getcurrentScreen 40 postOpenInitialization 40 sendData 40

commDLLName class variable 49

communication parameters, changing 102

communication protocol 110 Communications Manager

on accepting side 92 on initiating side 92

communications software 85 complex descriptors 98 compound verbs 90 configuring

APPC object 91 requester 104

confirm method 88 confirmation request 88 confirmed method 88, 94 connect message 111 connecting to emulator 53, 71 connection. See host

connection connectionless conversation

107 connection-oriented

conversation client 111 definition 107

connectPMWindowServices 55, 68, 77

connectPS 53, 71 connectPSForNotifyHostUpdat

e 53, 71


conversation changing state of 88, 103 determining if active 113 determining state 95 ending 94 establishing between TPs 88 highly scripted 87 holding 119 initializing 91 model 87 protecting 87 scripts 87 sequence of 86 sequence of conversations

110 starting 93, 117, 119 status of 125 stopping 119 synchronizing 87 types of 107 verbs 88

conversationType 88, 94 conversion

of data 98, 100 converting PS coordinates 66 convertToXYPosition: 66 coordinates, converting 66 copyFieldToStringPosition:leng

th: 61 copying data to and from OIA

and host PS 61 copyNextInputFieldToStringFro

m: 61 copyOIA 61, 69 copyPS 62 copyPSToStringPosition:length

: 62 copyStringToFieldValue:

string: 62 copyStringToNextInputFieldFro

m:value: 62 copyStringToPSValue:at: 62 copyStringToPSValue:xy: 62

creating APPC object 91 APPC server 98 DDE client session 124 DDE server session 120 Descriptor object 98, 113 host screen object 12 instance of class EHLLAPI 50,

70 Socket object 109 SocketAddress object 108

cursor position, querying and setting 59

D

data buffers 113 conversion 98, 100 receiving asynchronously 89,

97 retrieving 42 transferring 100 transferring, asynchronously

115 DDE

classes 120 client session 123 conversation 117 enabling ObjectStudio DDE

support 120 overview 117 sample applications 128 server session 120 transactions 119, 127

DDEClientSession class 120 DDEServerSession class 120 deallocate 88, 94 defining

client TP, example 93 descriptor object 98

deleting a host screen object 13, 22, 24


descriptor class used for 98 complex 98 instance variables 98 objects 98 sample 100 simple 98 use of descriptors 98

Descriptor class description 107, 113 instance variables 114

Designer building interface with 24 displaying interface in 27 launching 22, 24 linking to host screens 29 testing the interface 28 using to create GUI 42

detecting errors 89 determining conversation

state 95 development cycle 11 differences between 3270 and

5250 68 disconnecting from emulator

53, 71, 78 disconnectPMWindowServices

55, 68, 77 disconnectPS 53, 71 disconnectPSForNotifyHostUpd

ate 53, 71 DLL, initializing EHLLAPI 10,

43, 50 doNotReportErrors 101 Dynamic Link Library. See DLL

and DLL, EHLLAPI

E

editing a host screen object 13, 21, 22

Editor, Host Screen closing 20 opening 13 using 14

EHLLAPI class

class methods 24, 50 class variables 49 Commbuilder tool classes

35 description 49 instance methods 52 instance variables 49 instances of 70, 71

creating instance of 50 DLL 10 example 78 generic 10 generic and specific support

41 initializing the DLL 43, 50 introduction 41 loading 43 loading class 10 prerequisites 43 reinitializing 51 typical uses for 42

EHLLErrorDisplay method 40 EHLLTEST class 10 elements, array 72 emulator

connecting and disconnecting 53, 71, 78

differences in implementation 68

intercept closing of 65 waiting for 76

emulator window, status of 54 emulators, in Windows 69 ending

conversation 94, 119 TP 89, 94

error handlers 66 errors

detecting 89 receiveAndPost: 97 reporting 101

example of EHLLAPI 78 excluding fields from interface

26


execute transaction 119 example 128 server response to 123

executeCommand: 127 executeDDEEventFor:is:from:

123 extracting field information 13

F

fieldOrder method 36 fields

adding 17 attributes 14, 25, 34 changing information 14 excluding from interface 26 extracting field information

13 identifying as screen

identifier 16 inserting 17 Item Type field information

25 length 14 naming 14, 34 navigating 48 order of 14 position 14 removing 17, 20 row and column 14

fields method 36 files, sending and receiving 51 findFieldLengthFrom:mode: 63 findFieldPositionFrom:mode:

63 findFieldXYFromXY: mode: 63 finding

last operation 126 value of item in exchange

126 flush 88, 94 folder for host screen objects

21 fonts in user interface 26

G

generated methods 28, 35 generating a default user

interface 22, 24, 27 generic EHLLAPI 10, 46 generic support of EHLLAPI 41 getAttributes 88, 94 getCurrentScreen method 40 getEAB class variable 49 getFirstLine method 38 getKey 64, 80 getLastLine method 38 getLine:line method 38 getting data from server 118 Graphical User Interface,

creating with ObjectStudio Designer 42

H

help 47, 118 hierarchy, protocol 117 host

availability 57, 75 copying data to and from

OIA 61 receiving files from session

51 sending keystrokes to 57, 76 update notification 58, 76

host connection, live rereading 19 testing with 28 vs. simulated 9, 12

Host Screen Editor closing 20 opening 13, 22 pop-up menu 22, 25, 32


host screen object creating 12 deleting 13, 22, 24 editing 13, 21, 22 folder 21 linking 29, 32 locating 21 naming 13, 20 printing 23 saving 20, 23 summary 23

host:service:proto: message 108

hostPS instance variable 49 HostScreen class

class methods 36 description 36 instance methods 36

HostSession class 35 description 38 instance methods 38

hot link 117

I

IBM 3270 Personal Communications 45

icons CommBuilder 11 Session 12

identifying a data unit 118 identifying screens 15 ids method 36 image, building server TP 103 initializeFor: 43, 50 initializing conversation 91 initializing EHLLAPI DLL 43, 50 initiate 124 initiate transaction

description 119 example 130

initiating conversations 86 inserting fields 17

instance methods Host Screen

at: label 36 fieldOrder 36 fields 36 ids 36 isAvailableOn:session

with:hostData 36 name 36 name:newName 36 screenLinks 37 setFieldOrder:newFieldOr

der 37 setFields:newFields 37 setIds:newIds 37 setScreenLinksTo:newLink

s 37 totalFields 37 totalFields:total 37

Host Session activateEmulator 38 at:fieldName 38 at:fieldName put:text 38 buildErrorMessage:msg

number:num 38 changeTo:screen 38 getFirstLine 38 getLastLine 38 getLine:line 38 isActiveScreenNamed:na

me 38 lastError 38 lastFunction 38 queryActiveScreen 39 queryAllFields 39 setActiveScreenTo:screen

Name 39 waitForPS 39 waitForPSTimeout:time

39 in class EHLLAPI 52

instance of class EHLLAPI creating 70 multiple 71


instance variables codePage 49 for APPC object 91 for class EHLLAPI 49 for Descriptor

class 114 object 98

for system 91 hostPS 49 longName 49 psColumns 49 psId 49 psRows 49 psSize 49 sessionType 49

intercepting closing of emulator session

65 keystrokes 64

isActiveScreen Named:name method 38

isAvailableOn:session with:hostData method 36

item definition 118 finding value of 127

Item Type 25

K

keyboard, releasing and reserving 65

keys, mnemonics 84 keystrokes

intercepting 64 mnemonics 80 sending to host 57, 76

keywords, looking for 60, 76

L

lastError method 38 lastFunction method 38 lastOperation 126 Link Type

Send Data 34 Send Key 33

linking client and server 118, 121, 122

linking to host screens linking host screens 32 moving between screens 33 Screen link menu option in

Host Screen Editor 24 setting up 32 using Designer 29

live host connection displaying session icons with

12 loading EHLLAPI class with

10 rereading 19 testing with 28

Loadable Applications Browser 10

loading CommBuilder 11 loading EHLLAPI 43 loading TCP/IP 106 loading the EHLLAPI class 10 Logical Unit

allocating session between local and partner 88

definition 85 send buffer 88, 89 sending contents of local

send buffer 88 sessions 85

longName instance variable 49 method 55

looking for keywords 60, 76 LU. See Logical Unit


M

messages, sequence of 110 method reference 47 methods

allocate 88, 93 APPC 88 changePMWindowStatus:x:y:

dx:dy:behind: 77 changePMWindowStatusFlags

:x:y:dx:dy:behind: 54 changePSWindowNameTo:

54, 68 changeSwitchListLTNameTo:

54, 68 checkPSFor: 60 codePage 55 confirm 88 confirmed 88, 94 connectPMWindowServices

55, 68, 77 connectPS 53, 71 connectPSForNotifyHostUpda

te 53, 71 conversationType 88, 94 convertToXYPosition: 66 copyFieldToStringPosition:le

ngth: 61 copyNextInputFieldToStringF

rom: 61 copyOIA 61, 69 copyPS 62 copyPSToStringPosition:lengt

h: 62 copyStringToFieldValue:at:

62 copyStringToNextInputFieldF

rom:value: 62 copyStringToPSValue:at: 62 deallocate 88, 94 disconnectPMWindowService

s 55, 68 disconnectPS 53 disconnectPSForNotifyHostU

pdate 53 doNotReportErrors 101 findFieldLengthFrom:mode:

63 findFieldPositionFrom:mode:

63 findFieldXYFromXY:mode: 63 flush 88, 94

generated 28, 35 getAttributes 88, 94 getKey 64, 80 initialize for: 50 initializeFor: 43 longName 55 newPsId: 50, 70 pauseTime: 57, 76 postInterceptStatusKeyAccep

ted: 64, 77 prepareToReceive 88, 94 psColumns 55 psId 55 psRows 56 psSize 56 queryCloseIntercept 65, 68 queryCursorLocation 59 queryCursorXY 59 queryFieldAttributeAt: 63,

69 queryHostUpdate 58, 76 queryPMWindowCoordinates

56, 68 queryPMWindowStatus 56,

68 querySessions 50 receiveAllocate 88 receiveAndPost: 89, 94, 97 receiveAndPost:descriptor:

89, 94 receiveData 89, 94 receiveDataDescriptor: 89,

94 receiveFileParams: 51, 68 receiveImmediate 89, 94 receiveImmediateDescriptor:

89, 94 release 65 reportErrors 101 requestToSend 89, 94 reserve 65 resetPSWindowName 56 resetSwitchListLTName 56 resetSystem 51 runProfileName:mode: 69 searchFieldFor: from: 63 searchForScreen 76 searchForScreenContaining:

withTimeout: 60, 76 searchPSFor:from: 60 sendData: 89, 94 sendData:descriptor: 89, 94


methods (continued) sendError 89, 94 sendFileParams: 51, 68 sendKeyValue: 57, 69, 76,

77, 80 setConversationTypeTo: 92 setCursorLocationTo: 59 setCursorXYTo: 59 setLUAliasTo: 92 setModeNameTo: 92 setPLUAliasTo: 92 setRemoteTPNameTo: 92 setReturnStatusTo: 92 setSecurityTo: 92 setSessionParamsTo: 51, 71,

75 setSpecialTableTo: 99 setSyncLevelTo: 92 setTPNameTo: 92 start 89, 93, 98 startCloseIntercept 65, 68 startHostNotifyEventSource:

58, 76 startKeystrokeIntercept 77 startKeystrokeInterceptKeys:

64 stop 89, 94 stopCloseIntercept 65, 66,

68 stopHostNotify 58, 76 stopKeystrokeIntercept 64 testRTS 89, 94 verbs 88 wait 57, 75 xe 62

methods not supported for 5250 68 for Attachmate 70 for Rumba 69

mnemonics @A and @lowercase letters

83 @A and @uppercase letters

82 alphanumeric (special)

characters 84 for keystrokes 80 lowercase letters 81 numbers 81 special characters 84 supported keys 84 uppercase letters 80

models, conversation 87 modes, operation 113 modifying the translation

module 100 monitoring user input 42 moving between screens,

using keys or text 33 multiple instances of class

EHLLAPI 71

N

name method 36 name of server 118, 121 name:application:topic: 124 name:newName method 36 naming a host screen object

13, 20 Netsoft NS/Elite 45 Netsoft NS/ElitePlus 45 network address 108 new instance of class EHLLAPI

50, 70 newFor: message 109 newPsId: 50, 70

O

object APPC status change 97 configuring APPC 91 descriptor 98

ObjectStudio Designer. See Designer

ObjectStudio Opentalk Communication Layer 133

OIA 48 OIA, copying data to 61 online help 47 opening the Host Screen

Editor 22 Opentalk Communication

Layer 133 operation modes 113 Operator Information Area.

See OIA overview of DDE 117


P

parameters resetting 51 setting 51, 71

passwords 87 pauseTime: 57, 76 PF buttons

creating 26 methods for 28 moving between screens 32,

33 poke transaction 127 position, screen 52 postInterceptStatusKeyAccept

ed: 64, 77 postOpenInitialization method

40 prepareToReceive 88, 94 prerequisites to using EHLLAPI

43 presentation space

connecting to 53, 71 converting coordinates 66 copying data to 61 definition 48 disconnecting from 53, 71,

78 searching 60 waiting for 75

preventing user from entering data 65

printing host screen object summary 23

privateGetOption message 113 privateSetOption:value:

message 113 protocol

communication 110 description 87 hierarchy 117

PS. See presentation space psColumns

instance variable 49 method 55

psId instance variable 49 method 55

psRows instance variable 49 method 56

psSize instance variable 49 method 56

Q

queryActiveScreen method 39 queryAllFields method 39 queryCloseIntercept 65, 68 queryCursorLocation 59 queryCursorXY 59 queryFieldAttributeAt: 63, 69 queryHostUpdate 58, 76 querying

cursor position 59 host updates 58, 76 session details 50 status of emulator window

54 queryPMWindowCoordinates

56, 68 queryPMWindowStatus 56, 68 querySessions 50

R

receiveAllocate 88 receiveAndPost: 89, 94, 97 receiveAndPost:descriptor: 89,

94 receiveData 89, 94 receiveData message 110 receiveDataDescriptor: 89, 94 receiveFileParams: 51, 68 receiveImmediate 89, 94 receiveImmediateDescriptor:

89, 94 receiving data, asynchronously

89, 97 receiving files 51 refreshing the workplace 21 registering the server 121 reinitializing EHLLAPI 51 release 65 releasing keyboard 65 removing fields 17, 20 renaming screens 24 reportErrors 101 reporting errors 101


request 127 request transaction 118

example 130 requestOf: 127 requestToSend 89, 94 reserve 65 reserving keyboard 65 resetPSWindowName 56 resetSwitchListLTName 56 resetSystem 51 resetting session parameters

51 retrieving data 42 retrieving descriptor object 98 return codes 66 RUMBA 45, 46 runProfileName:mode: 69

S

sample application 102 sample DDE applications 128 saving

host screen object summary 23

host screen objects 20 Screen Editor pop-up menu 19 screen identifier

fields as 16 screen linking

linking host screens 32 moving between screens 33 setting up 32

screenLinks method 37 screens

changing 54 converting coordinates 66 describing position in 52 identifying 15 linking 24 method 36 moving between 33 renaming 24 searching for 60, 76

scripts, conversation 87 searchFieldFor:from: 63 searchForScreen 76 searchForScreenContaining:wi

thTimeout: 60, 76 searching for screens 60, 76 searching the presentation

space 60

searchPSFor:from: 60 security 87 send buffer of LU 89 Send Data button methods 28 sendData method 40 sendData: 89, 94 sendData:descriptor: 89, 94 sendError 89, 94 sendFileParams: 51, 68 sending

and receiving files 51 data

notifying 89 to host 34 to server 118

key to host 33 keystrokes to host 57, 76

sendKeyValue: 57, 69, 76, 77, 80

sequence of messages 110 server

building TP image 103 creating an APPC 98 creating DDE server session

120 DDE communication and 117 getting data from 119, 122 linking to client 118, 122 methods 120 name 118, 121 network communication and

106 registering 121 response to client

transactions 121 sample application 128 sending data to 118, 122

session creating client 124 creating server 120 finding last 126 querying details 50 receiving files from 51 sending files from 51 setting parameters 71

session icons 12 sessionType instance variable

49 setActionNamed:to: 125 setActiveScreenTo:screenNam

e method 39 setConversationTypeTo: 92


setCursorLocationTo: 59 setCursorXYTo: 59 setDDEApplication:topics: 121 setFields:newFields method 37 setIds:newIds method 37 setLUAliasTo: 92 setModeNameTo: 92 setPLUAliasTo: 92 setRemoteTPNameTo: 92 setReturnStatusTo: 92 setScreenLinksTo:newLinks

method 37 setSecurityTo: 92 setSessionParamsTo: 51, 71,

75 setSpecialTableTo: 99 setSyncLevelTo: 92 setTimeout: message 113 setting a timeout 113 setting cursor position 59 setting parameters 51, 71 settle time 75 setTPNameTo: 92 setValueOf:to: 127 setValueTo: 127 simple descriptors 98 simulated host connection 9,

10, 12 Socket class

creating instance of 109 description 107

socket operation modes 113 SocketAddress class

creating instance of 108 description 108

specific support of EHLLAPI 41 start 89, 93, 98 startCloseIntercept 65, 68 startDDEUpdateFor:using 122 startHostNotifyEventSource:

57, 58, 76 starting a conversation 117,

118 starting CommBuilder 9 starting TP 89, 93 startKeystrokeIntercept 77

startKeystrokeInterceptKeys: 64

startUpdate 126 state

changing conversation 88, 103

conversation 95 status

method 126 of conversation 126 of emulator window 54

stop closing of emulator session

65 method 89, 94

stopCloseIntercept 65, 66, 68 stopDDEUpdateFor:using: 122 stopHostNotify 58, 76 stopKeystrokeIntercept 64 stopping conversation 119 stopUpdate 126 synchronizing conversations 87 synchronous protocol 41

T

tasks, automating 42 TCP/IP

API 106 loading 106 receiving data of arbitrary

length 112 template object

creating 12 deleting 13 editing 13 naming 13

terminate transaction description 119 example 132 lastOperation method and

126 testing the interface 28 testRTS 89, 94 timeout

value 113 wait method and 57


topic definition 118 method 123 multiple topics 123

totalFields method 37 totalFields:total method 37 TP. See Transaction Program Transaction Program

as initiator or acceptor 86 building server image 103 conversations 86 creating profile for 102 defining client, example 93 definition 85 ending 89, 94 establishing conversation 88 name 91 starting 89, 93

transactions, DDE 119 transferring data

asynchronously 115 modifying the translation

module 100 translation module, modifying

100

U

unadvise transaction description 119 server response to 122

unlinking client and server 119 update notification from host

58, 76 user interface

features 28 fonts 26 generated methods 28 generating default 11, 22,

24, 27 linking between 32 linking to host screens 29 testing 28

users, monitoring 42

V

value of item in exchange 126 variables

class, for class EHLLAPI 49 instance

for class Descriptor 114 for class EHLLAPI 49

verbs. See also methods compound 90

W

wait 57, 75 waitForPS method 39 waitForPSTimeout:time

parameter 39 waiting for host 57 waiting for presentation space

75 Windows emulators 69 workplace, refreshing 21

X

xlate class variable 49

communications user's guide - cincom smalltalk

Documents