IRIS

®

3270 Emulator

Programming Guide

Document Number 007-1410-020

CONTRIBUTORS

Written by Sheri Chinen Biesen, Susan Thomas

Edited by Gail Larrick

Production by Julia Lin

Engineering contributions by Jay Lan, Fan Jiao, Robert Horen.

© Copyright 1991-1994, Silicon Graphics, Inc.— All Rights Reserved

This document contains proprietary and confidential information of Silicon

Graphics, Inc. The contents of this document may not be disclosed to third parties, copied, or duplicated in any form, in whole or in part, without the prior written permission of Silicon Graphics, Inc.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure of the technical data contained in this document by the Government is subject to restrictions as set forth in subdivision (c) (1) (ii) of the

Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and/ or in similar or successor clauses in the FAR, or in the DOD or NASA FAR

Supplement. Unpublished rights reserved under the Copyright Laws of the United

States. Contractor/manufacturer is Silicon Graphics, Inc., 2011 N. Shoreline Blvd.,

Mountain View, CA 94039-7311.

Silicon Graphics and IRIS are registered trademarks and IRIX is a trademark of

Silicon Graphics, Inc. Apollo is a registered trademark of Apollo Computer, Inc.

FrameMaker is a registered trademark of Frame technology, Inc. Hewlett-Packard is a registered trademark of Hewlett-Packard Company. IBM is a registered trademark of International Business Machines Corporation. Macintosh is a registered trademark of Apple Computer, Inc.

IRIS® 3270 Emulator Programming Guide

Document Number 007-1410-020

Contents

1.

List of Figures vii

List of Tables ix

Introduction xi

Typographical Conventions xii

Software and Hardware xii

Software xii

Hardware xiii

Network Configuration xiv

Product Support xiv

Silicon Graphics’ 3270 HLLAPI 1

IBM 3270 PC API to Silicon Graphics 3270 HLLAPI Changes 2

Silicon Graphics 3270 HLLAPI Capabilities 3 iii

Contents

2.

Subroutine Descriptions 4

Determine the Session ID 4

Initialize the Silicon Graphics 3270 HLLAPI Code 5

Determine the Value of the Session Parameters 6

Determine the Current Cursor Position 7

Connect to a 3270 Presentation Space 7

Disable Keyboard Input During HLLAPI Activity 8

Simulate Keyboard Data Entry 9

Enable Keyboard Input When HLLAPI Activity Is Completed 10

Disconnect from a 3270 Presentation Space 11

Copy Data between 3270 Presentation Space and Application

Data Area 11

Read OIA Status Group 13

Determine if the Screen Has Been Updated 13

Copy Status Line to an Application Data Area 14

Start Silicon Graphics Message Mode 15

Stop Silicon Graphics Message Mode 16

Read Silicon Graphics Message Mode Protocol Data Units 16

Read a 3270 Structured Field 17

Write 3270 Structured Field to the Host 18

Trace Silicon Graphics 3270 HLLAPI Data 19

Get Silicon Graphics 3270 HLLAPI Information for a Specified Session 19

User Entry Point into the IRIS 3270 Emulator 20

Troubleshooting 23

Troubleshooting Using the Trace Display Utility 23

Resolving Errors 24

Error Logging 24

Error Information Sources 25

Configuration Errors 25

Nonconfiguration Errors 25

SGI HLLAPI Trace Display Interpretation 26 iv

A.

B.

Silicon Graphics HLLAPI Error Messages 27

System Errors 27

Configuration Errors 28

Errors Reported Using 3270trace Only 28

Scan Code and Buffer Code Tables 29

Index 41

Contents v

List of Figures

Figure 2-1 3270 Trace Display Window 24 vii

List of Tables

Table B-1

Table B-2

Scan Codes 29

Buffer Codes 31 ix

Introduction

The Silicon Graphics

®

IRIS

®

3270 Emulator products provide a high-speed communications link between an IRIS-4D

TM

Series workstation and an IBM

® host computer running either Virtual Machine/Conversational Monitor

System (VM/CMS) or Multiple Virtual Storage/Time Sharing Option

(MVS/TSO).

With the IRIS 3270 Emulator, you can use an IRIS-4D workstation or server— with Systems Network Architecture (SNA), Transmission Control Protocol

(TCP), or 5080 Graphics System Workstation connectivity—to access your

IBM mainframe. The list below shows how the various link types of the IRIS

3270 Emulator product connect to an IBM host.

IRIS 3270 Emulator Product:

SNA 3270 Emulator

TCP 3270 Emulator

3270 for the 5080 Emulator

Connects to IBM Host through:

IBM 3705, 3725, or 3745 front end processor

IBM 8232 Ethernet controller

IRIS Channel Adapter (ICA)

This document describes how to create High-Level Language Application

Program Interface (HLLAPI) applications that interact with IBM host applications using Silicon Graphics’ 3270 HLLAPI programming environment and tools. It is organized to provide programming information, including 3270 HLLAPI functionality and troubleshooting.

Chapter 1 explains Silicon Graphics’ 3270 HLLAPI programming environment. Chapter 2 discusses troubleshooting using the trace display utility.

Note: For information on how to use and configure the IRIS 3270 Emulator, refer to the IRIS 3270 Emulator User’s Guide.

xi

Introduction

Typographical Conventions

These type conventions and symbols are used in this guide:

Italics Filenames, variables, IRIX command arguments, command flags, titles of publications, icon names

Bold Subroutine names

UPPERCASE IBM file names, command names and the names of keys used on IBM systems

Screen type

Bold Screen typ e

User input

()

Code examples, file excerpts, and screen displays

(including error messages)

(Parentheses) Following IRIX commands, they surround the reference page (man page) section where the command is described

[]

#

(Brackets) Surrounding optional syntax statement arguments

IRIX shell prompt for the superuser (root)

Software and Hardware

The IRIS 3270 Emulator software and hardware communicate between the

IRIS workstation and an IBM-host system running VM/CMS or MVS/TSO.

For information on system requirements, refer to the release notes included with your 3270 emulator product.

Software

The IRIS 3270 Emulator software includes these key files and directories:

/opt/3270/bin/ Contains all executable files for 3270

/opt/3270/chest/ Contains Toolchest menu files

/opt/3270/font/ Contains all fonts used by the emulator xii

Software and Hardware

/opt/3270/lib Contains libsgi3270.a, the 3270 HLLAPI link library.

/var/opt/3270/example/

Contains examples of 3270 HLLAPI, IRISXFR and

IND$FILE file transfer automation, file transfer input redirection, and keyboard input tracing.

/var/opt/3270/file/

Contains all log files used in problem determination

/var/opt/3270/spool/

Default location for files transferred to or from the host and screen captures

/var/opt/3270/lib/

Contains the 3270 configuration files

/usr/lib/X11/app-defaults/Setup3270

Contains color schemes for setup3270(1)

To use Silicon Graphics’ IRISXFR file transfer utility, you must install the

IRISXFR program on your IBM host. This software is distributed on a

1/2-inch tape, generated at 1600 bytes per inch (BPI). For information on how to install the host software, refer to the installation instructions included with the IRISXFR distribution.

Hardware

Warning:

Do not attempt to add boards or other upgrades in your system. Hardware upgrades should be installed only by Silicon

Graphics-certified personnel. Upgrades performed by noncertified persons void your warranty and may damage your system, or cause injury to improperly trained individuals.

xiii

Introduction

Network Configuration

The IRIS workstation running 3270 emulator software can be connected to an IBM host through these network configurations:

• a leased line using Synchronous Data Link Control (SDLC) via an IBM

37X5 front end processor

• Ethernet, Token Ring, or FDDI using IBM 3172 or equivalent controller

• local non-SNA channel attach using the IRIS Channel Adapter (ICA)

The typical IRIS 3270 Emulator hardware configuration includes:

• an IBM, or IBM compatible, mainframe computer

• an IBM host front-end processor running Network Control Program

(NCP)

• an IRIS SNA workstation running the IRIS 3270 Emulator software

(SNA mode) through an IRIS SNA gateway

• an IRIS SNA gateway running the IRIS 3270 Emulator software (SNA mode)

• an IRIS Channel Adapter gateway and connections

Product Support

Silicon Graphics provides comprehensive technical hardware and software product support and a maintenance program for IRIS products. For more information, refer to the release notes that accompany this product.

xiv

Chapter 1

1.

Silicon Graphics’ 3270 HLLAPI

The Silicon Graphics 3270 high-level language application program interface (HLLAPI) provides a programming environment and tools to create 3270 HLLAPI applications that communicate with IBM mainframe applications. SNA, TCP, and 5080 modes are supported. The Silicon

Graphics 3270 HLLAPI supports one session in SNA, TCP, and 5080 mode.

Model 2, 3, 4, and 5 terminals are supported.

The Silicon Graphics 3270 HLLAPI also supports 3270 structured field data flows when using an SNA, TCP, or 5080 connection.

Silicon Graphics 3270 HLLAPI applications allow you to:

• create your own customized 3270 user interface for displaying and processing keyboard information

• automate repetitive sequences and run dialogues between the IRIS and

IBM host unattended

• achieve faster throughput using structured field and Silicon Graphics

Message Mode capabilities

The Silicon Graphics 3270 HLLAPI provides HLLAPI functionality equivalent to IBM 3270 PC application program interface (API) as specified in the PC IBM 3270 Emulation Program, Version 3.00, Application Program

Interface and Host Reference manual, document version SC23-0960-0.

Input and return information is passed in a C structure rather than in registers. The values and meaning of returned codes are left unaltered. The number and type of the input structure members have also been maintained except for modifications introduced to support Silicon Graphics 3270

HLLAPI enhancements.

This chapter assumes that you understand the information contained in the

IRIS 3270 Emulator User’s Guide on using and configuring the IRIS 3270

Emulator.

1

Chapter 1: Silicon Graphics’ 3270 HLLAPI

IBM 3270 PC API to Silicon Graphics 3270 HLLAPI Changes

The following five changes map IBM PC Assembler implementation of

HLLAPI to Silicon Graphics HLLAPI using C language:

• A one-to-one mapping between service requests and C subroutine calls eliminates the need to map the information in registers AH, AL, BH,

BL, CX, and DX. This mapping also eliminates the need for the “system return code” that indicates improper values in these registers.

• The pointer to the parameter list (registers DX and ES) is replaced by a pointer to a structure.

• All instances of segment address/offset address in a parameter list are mapped onto pointers.

• All instances of “Must be zero/Unchanged” or “Reserved/Reserved” in the parameter list format definition are not implemented in the equivalent C structure.

• All elements of each C structure are aligned on 32-bit word boundaries.

This protects the user against future changes (a byte field can be expanded to 2 bytes or a short word expanded to a long word).

Three subdirectories under /var/opt/3270/example provide detailed examples of how to use the Silicon Graphics 3270 HLLAPI. All data structures used by the Silicon Graphics HLLAPI are defined in /usr/include/sys/hl_user_struct.h.

All constants used as input values or returned values are defined in /usr/

include/sys/hl_user_define.h. A short description of the contents of each subdirectory is provided below.

Case 1

Case 2

Case 3 provides an example of using hl_entry_point to create a filter routine within the Silicon Graphics-supplied t3279 program. In this case, the keyboard and display processing is done by Silicon Graphics-supplied routines.

is obsolete.

provides an example of a 3270 emulation with prespecified input and no display processing. The screen descriptors supply the input. A comment file contains the output generated and processes the screen descriptors. To view this file, enter: cat comment_output

2

Silicon Graphics 3270 HLLAPI Capabilities

You can also view a trace file by entering: cp trace log /usr/3270/file and then entering : display_3270trace

Note: All code may be copied and used in your development effort.

Silicon Graphics 3270 HLLAPI Capabilities

The capabilities of Version 7.0 of the Silicon Graphics 3270 HLLAPI are listed here. The features listed in italic type are not provided by the IBM 3270-PC

API.

• Determine the session ID

• Determine the value of the session parameters

• Determine the current cursor position

• Connect to the 3270 Presentation Space

• Disable keyboard input during HLLAPI activity

• Simulate keyboard data entry, that is, write data to the host application

• Enable keyboard input when HLLAPI activity is completed

• Disconnect from the 3270 Presentation Space

• Copy between the 3270 Presentation Space and an application data

• Read OIA group status

• Reinitialize Silicon Graphics 3270 HLLAPI after a UNIX

®

exec call while preserving the host session (for SNA, TCP, and 5080 modes only)

• Determine if the 3270 Presentation Space has been updated without a status line change

• Copy the status line from the 3270 Presentation Space into an application data area

• Start and stop Silicon Graphics Message Mode

• Read and write Silicon Graphics Message Mode Protocol Data Units

3

Chapter 1: Silicon Graphics’ 3270 HLLAPI

• Read and write 3270 structured fields

• Trace all data passing through the Silicon Graphics 3270 HLLAPI code

Subroutine Descriptions

Each description in this section explains the purpose of the subroutine, how it interacts with other Silicon Graphics 3270 HLLAPI subroutines, and the possible values for each element of the structure passed to the called routine.

See /usr/include/sys/hl_user_struct.h for the precise definition of each structure used by the service request subroutines. Appendix B lists the error messages that might be written to /var/opt/3270/file/hllapi_log in the event that an error is detected.

Determine the Session ID

Calling Sequence void hl_query_session_id (struct session_id

*session_id_struct)

Purpose

Usage

Verify that the specified session is available.

Call this subroutine once for each desired session at the start of an application using the Silicon Graphics 3270 HLLAPI.

Input Structure Members session_id link_type lu_name

0x01—indicating a request to connect to Session 1

0x1—indicating a 5080 connection

0x04—indicating SNA data over a leased line

0x05—indicating a TCP/IP connection reserved

Returned Structure Members session_ret 0x00—indicating success

0x02—if Session ID is invalid

0x2b—indicating a 3270 HLLAPI start up problem

4

Subroutine Descriptions shmid

0x38—indicating that shared memory used by the Silicon

Graphics HLLAPI could not be allocated

0x39—indicating that the maximum number of sessions are already running shared memory ID, used for t3279/ps3279 communication

Initialize the Silicon Graphics 3270 HLLAPI Code

Calling Sequence void hl_init (struct init *init_struct)

Purpose

Usage

Initialize the Silicon Graphics 3270 code at startup time.

Call this subroutine once, each time the Silicon Graphics

3270 HLLAPI application is started.

Input Structure Members session_id command

0x00—for first time initialization unique session number after an exec call command

0x01—indicates a first time initialization request

0x02—indicates an initialization request after an exec call config_name host_name full path name of configuration file

TCP/IP hostname for SGI gateway or IBM host terminal_pool LU name used only by SNA signal_rtn signal catching routine for SIGPOLL

Returned Structure Members session_ret 0x00—indicating success

5

Chapter 1: Silicon Graphics’ 3270 HLLAPI

Determine the Value of the Session Parameters

Calling Sequence void hl_query_session_params (struct session_params

*session_params_struct)

Purpose Determine the values of session characteristics that affect the operation of a Silicon Graphics 3270 HLLAPI application.

Usage This subroutine can be called at any time after the Session

ID has been determined. The Silicon Graphics 3270 HLLAPI deviates from the IBM 3270-PC API in that alternate screen sizes are supported. Extended Attributes are supported.

Programmed Symbols are not supported.

Input Structure Members session_id unique session number

Returned Structure Members session_type session_char

0x02—is always returned

0x00—if no extended attributes and no programmed symbols

0x40—if programmed symbols, but no extended attributes

0x80—if extended attributes, but no programmed symbols

0xc0—if extended attributes and programmed symbols session_rows number of rows in session’s Presentation Space session_cols session_ret number of columns in session’s Presentation Space

0x00—if successful

0x02—if Session ID is invalid

6

Subroutine Descriptions

Determine the Current Cursor Position

Calling Sequence void hl_query_session_cursor (struct session_cursor

*session_cursor_struct)

Purpose

Usage

Determine the current cursor position and type.

This subroutine must be called whenever the Silicon

Graphics 3270 HLLAPI application needs to determine the current cursor position and type. Row and column addresses start at 0, not 1.

Input Structure Members session_id unique session number

Returned Structure Members cursor_type cursor_row cursor_col cursor_pos status session_ret

0x00—if underscore cursor, always returned current row address of cursor current column address of cursor returned address, as offset

0x00—does not display cursor

0x01—displays cursor

0x00—if successful

0x02—if Session ID is invalid

Connect to a 3270 Presentation Space

Calling Sequence void hl_connect (struct connect *connect_struct)

Purpose Connect a Silicon Graphics 3270 HLLAPI application to an active 3270 Presentation Space.

7

Chapter 1: Silicon Graphics’ 3270 HLLAPI

Usage This subroutine serializes access to keyboard and copy services. The routine must be called at the start of an Silicon

Graphics 3270 HLLAPI application and normally is followed by a call to hl_reserve, which locks the keyboard, preventing operator input.

Input Structure Members session_id query_reply unique session number reserved

query_reply_len reserved

Returned Structure Members keyboard_ret 0x00—if successful

0x02—if Session ID is invalid

0x04—if session already connected for keyboard services

Disable Keyboard Input During HLLAPI Activity

Calling Sequence void hl_reserve (struct reserve *reserve_struct)

Purpose

Usage

Causes 3270 emulator to disable keyboard input.

Normally, this subroutine is called immediately after hl_connect to prevent the intermingling of operator- and application-generated keyboard input.

Input Structure Members session_id unique session number

Returned Structure Members keyboard_ret 0x00—if successful

0x02—if Session ID is invalid

0x04—if session not connected for keyboard services

8

Subroutine Descriptions

Simulate Keyboard Data Entry

Calling Sequence void hl_send_key (struct send_key *send_key_struct)

Purpose Sends keystroke data from an Silicon Graphics 3270

HLLAPI application as an operator would enter it from a keyboard.

Usage Used whenever the Silicon Graphics 3270 HLLAPI application wishes to send data to a host program. The

Silicon Graphics 3270 HLLAPI deviates from the IBM specification by allowing an unlimited number of keystrokes to be encoded in the keystroke list.

Note: 3270 Buffer Code format is supported for all values of CHAR_SET.

ASCII scan codes are supported only if CHAR_SET = US_ENGLISH in your configuration file.

n keystrokes

Scan

Code

#1

Shift

State

#1

. . . . . . . . . . . . . .

Scan

Code

#n

Shift

State

#n

Each scan code and shift state is an 8-bit quantity. See Appendix B, “Scan

Code and Buffer Code Tables” for scan code shift state definitions.

Input Structure Members session_id char_set unique session number character set in use (possible values for char_set are defined in hl_user_define.h; they range from HL_FRENCH to

HL_KATAKANA_ENGLISH)

Note: For Katakana applications, CHAR_SET = HL_KATAKANA implies that Katakana characters will be displayed. If English characters should be displayed, set CHAR_SET = HL_KATAKANA_ENGLISH.

keystroke_ptr pointer to list of scan code/shift state pairs total_keys total number of keystrokes to be sent to the host

9

Chapter 1: Silicon Graphics’ 3270 HLLAPI

Returned Structure Members keyboard_ret keys_sent

0x00—if successful and no AID generated

0x02—if Session ID is invalid

0x04—if session not connected for keyboard services

0x10—if invalid scan code or input inhibited condition

0x12—if successful and AID generated

0x37—if char_set invalid number of keys sent before processing ended

Enable Keyboard Input When HLLAPI Activity Is

Completed

Calling Sequence void hl_release (struct release *release_struct)

Purpose

Usage

Causes 3270 emulator to enable operator keyboard input.

If hl_reserve has been called, hl_release can be called to reenable keyboard input. The hl_disconnect subroutine also reenables keyboard input automatically.

Input Structure Members session_id unique session number

Returned Structure Members keyboard_ret 0x00—if successful

0x02—if Session ID is invalid

0x04—if session not connected for keyboard services

10

Subroutine Descriptions

Disconnect from a 3270 Presentation Space

Calling Sequence void hl_disconnect (struct disconnect *disconnect_struct)

Purpose Disconnect a Silicon Graphics 3270 HLLAPI application from an active 3270 Presentation Space.

Usage This subroutine serializes access to keyboard and copy string services. It must always be called prior to exiting the

Silicon Graphics 3270 HLLAPI application code.

Input Structure Members session_id unique session number

Returned Structure Members keyboard_ret 0x00—if successful

0x02—if Session ID is invalid

0x04—if session not connected for keyboard services

Copy Data between 3270 Presentation Space and

Application Data Area

Calling Sequence void hl_copy_data (struct copy_data *copy_data_struct)

Purpose Copy part or all of the data from the 3270 Presentation Space to the Silicon Graphics 3270 HLLAPI application data area or vice versa.

Usage Called whenever data must be moved from the 3270

Presentation Space to the application data area. It is also used to update the 3270 Presentation Space. Only the 3270 device buffer format is supported.

11

Chapter 1: Silicon Graphics’ 3270 HLLAPI

Input Structure Members source_id source_ptr source_beg source_end target_id target_ptr target_beg copy_mode

0x00—(application to 3270) unique session number (3270 to application)

0x00—(3270 to application) pointer to application data area (application to 3270) offset to first source character to be copied

(both directions) offset to last source character to be copied (both directions)

0x00—(3270 to application) unique session number (application to 3270)

0x00—(3270 to application) pointer to application data area (application to 3270) offset to starting copy position in target buffer

(both directions)

0x00—3270 field attributes not copied (both directions)

0x40—3270 field attributes copied (3270 to application)

Returned Structure Members copy_ret 0x00—if successful

0x02—if Session ID is invalid

0x03—if target is input inhibited

0x06—if invalid source definition

0x07—if invalid target definition

0x09—if truncation occurred

0x0e—if some or all of the target is protected

0x0f—if copy of field attributes not allowed

12

Subroutine Descriptions

Read OIA Status Group

Calling Sequence void hl_read_oiag (struct read_oiag *read_oiag_struct)

Purpose

Usage

Determine the current input inhibited state.

This subroutine determines when the 3270 Presentation

Space is ready to accept input. It is designed to be used in a polled mode or blocked mode with a timeout. Each unit of time represents 10 milliseconds.

Input Structure Members session_id mode timeout unique session number

0x01—if polling mode desired

0x02—if blocked mode with timeout desired

1 - 6000—if read_mode = 2; 0 otherwise

Returned Structure Members oiag_ret oiag_buf

0x00—if successful

0x02—if Session ID is invalid

0x23—if time out value not between 1 and 6000

5 bytes containing returned OIAG status (see p. 1-1 to reference document SC23-0960-0, p. 3-73)

Determine if the Screen Has Been Updated

Calling Sequence void hl_screen_status (struct screen_status

*screen_status_struct)

Purpose

Usage

Determine if any location on the screen has been updated.

This subroutine determines when the 3270 Presentation

Space or Status Line has been updated. It eliminates the need to call hl_read_oiag and hl_copy_data to determine if any location on the screen has been updated. It also

13

Chapter 1: Silicon Graphics’ 3270 HLLAPI provides a flag that indicates that a structured field has been received from the host and is waiting to be read by the user application. Each unit of time represents 10 milliseconds.

Input Structure Members session_id mode timeout unique session number

0x01—if polling mode desired

0x02—if blocked mode with timeout desired

1 - 6000—if read_mode = 2; 0 otherwise

Returned Structure Members screen_ret line_change sf_pending write_cmd partition filexfr_active

0x00—if screen has been updated

0x02—if Session ID is invalid

0x23—if time out value not between 1 and 6000

0x24—if the screen has not been updated

0x25—if Unix has detected an error (error code is in errno)

44 bytes, one for each line, 0 = unchanged and 1 changed. line_change[0] represents the status line

1—if a structured field is waiting to be read, 0 otherwise

1—if screen updated by Erase Write or Erase Write

Alternate command; 0 otherwise reserved reserved

Copy Status Line to an Application Data Area

Calling Sequence void hl_copy_status (struct copy_status

*copy_status_struct)

Purpose Provides the Silicon Graphics 3270 HLLAPI application with the ability to display and/or analyze all fields of the

3270 status line.

14

Subroutine Descriptions

Usage Used in error recovery or when the terminal display program is customer-supplied. If HL_NO_COPY is specified, the target_ptr is not used and it is assumed that

stat_pointer from the map data structure will be used to point to the status line. If HL_COPY_TO_APPL is used,

target_ptr must be defined.

Input Structure Members session_id mode target_ptr unique session number

HL_NO_COPY and HL_COPY_TO_APPL pointer to application data area (size >= 80 bytes)

Returned Structure Members copy_ret 0x00—if the status line has been copied

0x02—if Session ID is invalid

Start Silicon Graphics Message Mode

Calling Sequence void hl_start_msg (struct start_msg *start_msg_struct)

Purpose Allows the Silicon Graphics 3270 HLLAPI application to start Silicon Graphics Message Mode.

Usage This subroutine must be invoked once prior to calling hl_read_msg or hl_write_msg. (CUT mode only)

Input Structure Members session_id unique session number

Returned Structure Members message_ret 0x00—if successful

0x02—if Session ID is invalid

15

Chapter 1: Silicon Graphics’ 3270 HLLAPI

Stop Silicon Graphics Message Mode

Calling Sequence void hl_stop_msg (struct stop_msg *stop_msg_struct)

Purpose Allows the Silicon Graphics 3270 HLLAPI application to terminate Silicon Graphics Message Mode.

Usage Can be used to switch out of Silicon Graphics Message

Mode. It need not be called when disconnecting, since hl_disconnect terminates Silicon Graphics Message Mode automatically.

Input Structure Members session_id unique session number

Returned Structure Members message_ret 0x00—if successful

0x02—if Session ID is invalid

Read Silicon Graphics Message Mode Protocol Data Units

Calling Sequence void hl_read_msg (struct read_msg *read_msg_struct)

Purpose Read a Silicon Graphics Message Mode Protocol Data Units sent by the host.

Usage This subroutine is typically called when the application expects the host to send Message Mode data rather then normal 3270 data. All returned data is encoded in 3270

Buffer Code. It is assumed that each screen is written using the 3270 Erase Write command and that each screen in

“unformatted”. Each Set Buffer Address (0,0) is marked by an 0xff character inserted into the data stream. If

HL_NO_COPY is specified, the data_ptr is not used. Instead, the mba_ptr from the map data structure is used into point to the 64 Kb Message Mode ring buffer. The map data pointer is initialized by calling hl_map_data. The

16

Subroutine Descriptions application must manage its own offset into the ring buffer after initialization. If HL_COPY_TO_APPL is used, data_ptr must be defined.

Input Structure Members session_id mode data_ptr data_size unique session number

HL_NO_COPY and HL_COPY_TO_APPL pointer to application data area size of the application data area

Returned Structure Members message_ret data_count

0x00—if successful

0x02—if Session ID is invalid

0x04—if session not connected for keyboard services

0x21—if the receive time out value has been exceeded

0x26—if the application data size < received data size

0x28—if Silicon Graphics Message Mode has not been invoked number of bytes stored in application data area

Read a 3270 Structured Field

Calling Sequence void hl_read_sf (struct read_sf *read_sf_struct)

Purpose

Usage

Read a 3270 Structured Field that has been sent by the host.

This subroutine is called whenever an Silicon Graphics 3270

HLLAPI application expects a Structured Field from the host other than the Read Partition Query and Outbound

3270DS. The application need not call this routine unless it has already detected a structured field pending using the flag word provided by hl_screen_status. Each call to hl_read_sf returns the contents of a Structured Field.

(SDLC)

17

Chapter 1: Silicon Graphics’ 3270 HLLAPI

Input Structure Members session_id data_ptr data_size unique session number pointer to application data area size of the application data area

Returned Structure Members data_count message_ret number of bytes stored in application data area

0x00—if successful

0x02—if Session ID is invalid

0x04—if session not connected for keyboard services

0x26—if the application data size < received data size

Write 3270 Structured Field to the Host

Calling Sequence void hl_write_sf (struct write_sf *write_sf_struct)

Purpose

Usage

Send a 3270 Structured Field to the host.

This subroutine is called whenever the Silicon Graphics

3270 HLLAPI application must send a 3270 Structured Field to the host other than Query Reply and Inbound 3270DS.

The Structured Field can contain up to 4K bytes of data.

(DFT mode only)

Input Structure Members session_id data_ptr data_count unique session number pointer to application data area number of bytes stored in application data area

18

Subroutine Descriptions

Returned Structure Members message_ret 0x00 if successful

0x02 if session ID is invalid

0x04 if session not connected for keyboard services

0x27 if the application data size > 64K bytes

Trace Silicon Graphics 3270 HLLAPI Data

Calling Sequence void hl_trace (struct session_id *session_id_struct)

Purpose

Usage

Trace keyboard input and host output.

This routine is called whenever the Silicon Graphics 3270

HLLAPI application wants to trace all data passing through the Silicon Graphics 3270 HLLAPI. The trace data can be displayed by invoking /opt/3270/bin/display_3270trace.

Input Structure Members session_id unique session number

Returned Structure Members

None

Get Silicon Graphics 3270 HLLAPI Information for a

Specified Session

Calling Sequence void hl_map_data (struct map_data *map_data_struct)

Purpose Eliminate need to copy data from Silicon Graphics

Presentation Space image into a local buffer provided by the

Silicon Graphics 3270 HLLAPI application.

Usage To minimize data copies and allow for different 3270

Presentation Space images, call once for each session at initialization time.

19

Chapter 1: Silicon Graphics’ 3270 HLLAPI

Input Structure Members session_id ps_ptr stat_ptr mba_ptr ea_ptr ps_rows_ptr ps_cols_ptr unique session number pointer to start of the 3270 Presentation Space pointer to start of the status line pointer to start of the Silicon Graphics Message Mode circular buffer pointer to start of the 3270 Extended Attribute Buffer pointer to location containing number of rows pointer to location containing number of columns

Returned Structure Members session_ret 0x00—if successful

User Entry Point into the IRIS 3270 Emulator

Calling Sequence void hl_entry_point (struct entry_point

*entry_point_struct)

Purpose Provide an entry point for user-supplied code enhancements to the IRIS 3270 Emulator.

Usage This routine is called each time through the main processing loop for the IRIS 3270 Emulator. It is designed to provide an inline filter capability for user-specific needs allowing the filter routine to specify when the 3270 Presentation Space should be displayed for user viewing.

Input Structure Members session_id unique session number

20

Subroutine Descriptions

Returned Structure Members transfer_ret 0x35—Display the 3270 Presentation Space

0x36—Do not display the 3270 Presentation Space

0x3c—Poll 3270 Presentation Space for updates

21

Chapter 2

2.

Troubleshooting

This chapter explains how to gather information and resolve or report problems that might appear when programming the IRIS 3270 Emulator.

The chapter includes information on using the trace utility to resolve

HLLAPI errors.

Troubleshooting Using the Trace Display Utility

To track errors and more easily troubleshoot problems, you can use 3270

Trace to record all data sent to and received by the 3270 emulation process, then use the Trace Display utility to display the recorded data.

To record the presentation space data, turn on the 3270 Trace option from the

Miscellaneous box in the Set Up 3270 window, as described in “Selecting

Miscellaneous Options,” in Chapter 1 of the IRIS 3270 Emulator User’s Guide.

After you use 3270 Trace to record the presentation space, you can display the data using the Trace Display utility by entering: display_3270trace

The full-screen window in Figure 2-1 appears.

23

Chapter 2: Troubleshooting

Resolving Errors

Figure 2-1 3270 Trace Display Window

This section deals with the process for resolving errors. Error messages are listed in Appendix A, “Silicon Graphics HLLAPI Error Messages.”

Error Logging

Errors reported by the IRIS 3270 Emulator are logged in the file /var/opt/3270/

file/t3279_log.PID. All errors in this file are also displayed in an error message window. Errors reported by the SGI HLLAPI library are logged in /usr/adm/

SYSLOG. These errors are not visually displayed, since it is expected that

24

Resolving Errors each 3270 emulator coded on top of the SGI HLLAPI interface has its own style of user interface.

Error Information Sources

For configuration errors, the error information in the log files should be enough. For other errors, additional information can be gathered by setting the 3270 Trace option to Yes using the Set Up 3270 window as described in

Chapter 1 of the IRIS 3270 Emulator User’s Guide.

Configuration Errors

For configuration errors, look up the error message and make the appropriate correction using the Set Up 3270 window. For ASCII terminal users, see Appendix B of the IRIS 3270 Emulator User’s Guide for more information on editing the configuration file.

If the error does not go away, refer to your release notes for product support information.

Nonconfiguration Errors

To find and correct errors that are not related to configuration problems, perform these steps:

1.

Set the 3270 Trace option to Yes using the Set Up 3270 window.

2.

Start the terminal emulator from the icon.

3.

Re-create the problem.

4.

Report the problem. Refer to your release notes for instructions on where to send the files below:

• all executable files from your /opt/3270/bin directory

• /var/opt/3270/file/*_log* (all log files)

5.

If the Silicon Graphics 3270 Emulator is terminated by program error, a core file is saved in /usr/var/opt/spool. Send this file in addition to those mentioned in step 4.

25

Chapter 2: Troubleshooting

6.

If the problem occurs during a file transfer using IRISXFR, enter sgixfr versions while logged in to your host ID. Report the returned information along with the information collected in steps 1-3.

SGI HLLAPI Trace Display Interpretation

If you are a developer working with the SGI HLLAPI, use the Trace Display option in the 3270 icon to display the data contained in the trace file /var/opt/

3270/file/trace_log.

These types of information are traced: [BULLET LIST]

• An image of the 3270 Presentation Space. The color code is blue.

• An image of the 3270 Status Line. The color code is white.

• “Line Change Bits.” 1 = changed and 0 = no change. The leftmost bit is for the status line. The other bits are for lines 1 to n with n being 24, 27,

32, or 43. The color code is yellow.

• A hexadecimal display of all attributes with their row and column position. Row and column numbers start at 0, not 1. The color code is red.

• Keyboard input. Use Appendix B to interpret the scan codes and shift state representation. The color code is green.

• A hexadecimal display of structured field data read by hl_read_sf.c and written by hl_write_sf.c. The color code for received data is blue and for transmitted data, yellow. The characters are in EBCDIC.

• A hex display of SGI Message Mode data read by hl_read_msg.c and written by hl_write_msg.c. The color code for received data is blue and for transmitted data, yellow. The characters are in 3270 buffer code.

26

Appendix A

A.

Silicon Graphics HLLAPI Error Messages

System Errors

The messages listed in this appendix reside in the file /usr/adm/SYSLOG.

These errors are generated by the Silicon Graphics HLLAPI routines described in Chapter 1, “Silicon Graphics’ 3270 HLLAPI.” The messages are divided into two categories: system errors and configuration errors. All system errors should be reported immediately to your SGI service representative. All configuration errors can be eliminated or corrected by changing parameter values in /var/opt/3270/lib/t3279rc.$LOGNAME.

In the error list below, N is the UNIX error number as defined in the intro online man page. The messages are listed below:

If any of these errors occurs, refer to your release notes for product support information.

ERROR: Open of /dev/t3270c0 failed errno = N

ERROR: Download ioctl call failed errno = N

ERROR: Open of /var/opt/3270/file/exec.info failed errno = N

ERROR: Open of /usr/adm/SYSLOG failed errno = N

ERROR: Open of /var/opt/3270/file/trace_log failed errno = N

ERROR: Open of 3270 configuration file failed errno = N

ERROR: Fstat call for /var/opt/3270/lib/t3279uc failed errno = N

ERROR: Malloc call failed errno = N

ERROR: Mmap call failed errno = N

ERROR: Read of /var/opt/3270/lib/t3279uc failed errno = N

ERROR: SCR_UD ioctl call failed errno = N

ERROR: SET_DID ioctl call failed errno = N

27

Appendix A: Silicon Graphics HLLAPI Error Messages

Configuration Errors

If a configuration error occurs, see Appendix B in the IRIS 3270 Emulator

User’s Guide for the valid inputs for each configuration parameter. If changing the inputs does not solve the problem, refer to your release notes for product support information.

ERROR: RECV_TIMEOUT must be between 1000 and 65535

ERROR: SEND_TIMEOUT must be between 1 and 2047

ERROR: KEY_TIMEOUT must be between 1 and 31

ERROR: LINK missing or defined improperly

ERROR: CHAR_SET missing or improperly defined

ERROR: MODEL must be between 2 and 5

Errors Reported Using 3270trace Only

Could not get temporary space to read in trace file.

Error detected while reading /var/opt/3270/file/trace_log: errno = N.

Illegal character detected in line number - Please reenter.

Line number too large - Please reenter.

No data in the trace file.

Search string contains zero characters - Please reenter.

28

Appendix B

B.

Scan Code and Buffer Code Tables

5E

5F

6A

6E

2F

3F

4F

5A

05

06

07

08

10

0C

0D

0F

1F

Table B-1 Scan Codes

Scancode a

0B

Base

Erase EOF

Invalid

Tab

PF2

PF4

PF6

PF8

PF10

CR

PF12

PF24 cursor right

PA2

Invalid

Clear

PF1

PF13

PF14

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Alt

Erase Input

Attn

Invalid

Invalid

Invalid

Sysrq

Invalid

Invalid

Invalid

Invalid

29

Appendix B: Scan Code and Buffer Code Tables

Table B-1 (continued)

Scancode a

48

50

56

57

37

38

40

47

20

27

28

30

11

17

18

62

63

64

65

66

58

60

61

61

Scan Codes

Base

PF21

PF22

PF11

PF23

PF7

PF19

PF20

PF9 reset

PF3

PF15

PF16

PF5

PF17

PF18

Enter cursor down

Backspace cursor left

Invalid cursor up

Back Tab

Insert

Delete

30

Alt

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid home

Invalid

Invalid

Invalid

Invalid

Table B-1 (continued) Scan Codes

Scancode a

Base Alt

67

70

71

PA1

Field Mark

Dup

Invalid

Dev Cncl

Test

72

73

Ident

Shift On

Invalid

Shift Off a. All scan codes other than those listed are Invalid. Invalid scan codes are handled as indicated in the Write Keystroke service.

Table B-2 Buffer Codes

Character Description ASCII Hex

Null

Greater Than sign

Less Than sign

Left Bracket

Right Bracket

Right Parenthesis

>

[

<

)

]

Invalid

3E

3C

5B

5D

29

00

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

3270 Device

Buffer Hex

07

08

09

0A

0B

0C

03

04

05

06

00

01

02

Valid Across

Languages y n n y n y n n n n y n n

31

Appendix B: Scan Code and Buffer Code Tables

Table B-2 (continued)

Character Description

Buffer Codes

ASCII Hex

Left Parenthesis

Right Brace

Left Brace

Blank

Equal sign

Apostrophe

Double Quote

Slash

Reverse Slash

Vertical Bar

Broken Vertical Bar

Question Mark

Exclamation Mark

Dollar sign

Cent Sign

Lb. sign - Lire

Yen sign

Peseta

Intl. Monetary sign

0 (F0)

1 (F1)

2 (F2)

3 (F3)

{

}

(

/

\

|

=

'

"

3F

21

24

9B

2F

5C

B3

7C

20

3D

27

22

28

7D

7B

30

31

32

33

9C

9D

9E

0F

•

¤

£

¥

$

¢

!

?

2

3

0

1

Valid Across

Languages n n y n n n y n y n y y y n n y y y

21 n n n n

3270 Device

Buffer Hex

18

19

1A

1B

14

15

16

17

10

11

12

13

0D

0E

0F

20

21

22

23

1C

1D

1E

1F

32

Table B-2 (continued)

Character Description

Buffer Codes

ASCII Hex

4 (F4)

5 (F5)

6 (F6)

7 (F7)

8 (F8)

9 (F9)

Beta

Section Symbol

Number sign

At sign

Percent sign

Underscore

Ampersand

Hyphen

Period

Comma

Colon

Plus sign

Not Symbol

Overbar

Degree

Circumflex

+

¬

:

,

§

#

15

23

@ 40

% 25

.

-

_ 5F

& 26

2D

2E

9

ß

7

8

4

5

6

37

38

39

F1

34

35

36

^

2C

3A

2B

AA

Invalid

Invalid

Invalid

5E

Valid Across

Languages y y y y n y n n y n y y y y y n n n n y n y y

3270 Device

Buffer Hex

2F

30

31

32

2B

2C

2D

2E

27

28

29

2A

24

25

26

37

38

39

3A

33

34

35

36

33

Appendix B: Scan Code and Buffer Code Tables

Table B-2 (continued)

Character Description

Buffer Codes

ASCII Hex

Tilde

Diaeresis

Grave Accent

Acute Accent

Cedilla a Grave Small e Grave Small i Grave Small o Grave Small u Grave Small a Tilde Small o Tilde Small y Diaeresis Small a Diaeresis Small e Diaeresis Small

ä

ë

8D

95

97

Invalid

Invalid

98

Invalid

Invalid

7E

Invalid

60

27

Invalid

85

8A

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

84

89

ù

ã

ì

ò

õ

ÿ

à

è

´

ç

`

¨

~

Valid Across

Languages n n n n n n n n n n n n n n n n n n n n n n n

3270 Device

Buffer Hex

46

47

48

49

42

43

44

45

3E

3F

40

41

3B

3C

3D

4E

4F

50

51

4A

4B

4C

4D

34

Table B-2 (continued)

Character Description

Buffer Codes

ASCII Hex i Diaeresis Small o Diaeresis Small u Diaeresis Small a Circumflex Small e Circumflex Small i Circumflex Small o Circumflex Small u Circumflex Small a Acute Small e Acute Small i Acute Small o Acute Small u Acute Small n Tilde Small a Grave Capital e Grave Capital i Grave Capital o Grave Capital u Grave Capital a Tilde Capital e Tilde Capital

96

A0

82

A1

A2

A3

A4

Invalid

83

88

8C

93

8B

94

81

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

ó

ú

ã

í

é

û

á

î

ô

â

ê

ï

ö

ü

Valid Across

Languages n n n n n n n n n n n n n n n n n n n n n n n

3270 Device

Buffer Hex

5D

5E

5F

60

59

5A

5B

5C

55

56

57

58

52

53

54

65

66

68

69

61

62

63

64

35

Appendix B: Scan Code and Buffer Code Tables

Table B-2 (continued)

Character Description

Buffer Codes

ASCII Hex a Diaeresis Capital e Diaeresis Capital i Diaeresis Capital o Diaeresis Capital u Diaeresis Capital a Circumflex Capital e Circumflex Capital i Circumflex Capital o Circumflex Capital u Circumflex Capital a Acute Capital e Acute Capital i Acute Capital o Acute Capital u Acute Capital n Tilde Capital a Small

Invalid

Invalid

Invalid

Invalid

Invalid

Invalid

Ä 8E

Invalid

Invalid

Ö 99

Ü 9A

Invalid

Invalid

Invalid

Invalid

É

Invalid

Invalid

90

Invalid

Invalid

Invalid

Ñ A5 a 61

Valid Across

Languages n n n n n n n n n n n n n n n n y n n n n n n

3270 Device

Buffer Hex

75

76

77

78

71

72

73

74

6D

6E

6F

70

6A

6B

6C

7D

7E

7F

80

79

7A

7B

7C

36

Table B-2 (continued)

Character Description

Buffer Codes

ASCII Hex i Small j Small k Small l Small m Small n Small o Small p Small b Small c Small d Small e Small f Small g Small h Small q Small r Small s Small t Small u Small v Small w Small x Small l k j i o p m 6D n 6E

6F

70

69

6A

6B

6C g h f e b c d

65

66

67

68

62

63

64 t s q r u v

75

76 w 77 x 78

71

72

73

74

Valid Across

Languages y y y y y y y y y y y y y y y y y y y y y y y

3270 Device

Buffer Hex

8C

8D

8E

8F

88

89

8A

8B

84

85

86

87

81

82

83

94

95

96

97

90

91

92

93

37

Appendix B: Scan Code and Buffer Code Tables a Capital b Capital c Capital d Capital e Capital f Capital g Capital h Capital i Capital j Capital k Capital l Capital m Capital n Capital o Capital

Table B-2 (continued)

Character Description

Buffer Codes

ASCII Hex y Small z Small

Diphthong Small o Slash Small a Overcircle Small c Cedilla Small

J

K

H 48

I 49

4A

4B

L 4C

M 4D

N 4E

O 4F y z

æ

F

G

D

E

B

C

Invalid

A 41

42

43

44

45

46

47

79

7A

91

Invalid

86

87

Invalid

Valid Across

Languages y y y y y y y y n y n n y y n y y y y y y y y

3270 Device

Buffer Hex

A3

A4

A5

A6

9F

A0

A1

A2

9B

9C

9D

9E

98

99

9A

AB

AC

AD

AE

A7

A8

A9

AA

38

Table B-2 (continued)

Character Description

Buffer Codes

ASCII Hex p Capital q Capital r Capital s Capital t Capital u Capita; v Capital w Capital x Capital y Capital z Capital

Diphthong Capital o Slash Capital a Overcircle Capital c Cedilla Capital

Semicolon

Asterisk

P 50

Q 51

R 52

S

T

53

54

U 55

V 56

;

*

Y

Z

W 57

X 58

59

5A

Æ 92

Invalid

8F

80

3B

2A

3270 Device

Buffer Hex

BA

BB

BC

BD

B6

B7

B8

B9

BE

BF

B2

B3

B4

B5

AF

B0

B1

Valid Across

Languages n n n n y y y y y y y y y y y y y

39

Index

B buffer codes , 29

D display_3270trace , 23

E error messages

3270trace , 28

HLLAPI configuration errors , 28

HLLAPI system errors , 27

H hl_connect , 7 hl_copy_data , 11 hl_copy_status , 14 hl_disconnect , 11 hl_entry_point , 20 hl_init , 5 hl_map_data , 19 hl_query_session , 6 hl_query_session_cursor , 7 hl_query_session_id , 4 hl_read_msg , 16 hl_read_oiag , 13 hl_read_sf , 17 hl_release , 10 hl_reserve , 8 hl_screen_status , 13 hl_send_key , 9 hl_start_msg , 15 hl_stop_msg , 16 hl_trace , 19 hl_write_sf , 18

HLLAPI , 26 capabilities , 3 features , 2 subroutines , 4

HLLAPI subroutines hl_query_session_id , 4

I

IRIS 3270 Emulator introduction , xi network configuration , xiv product support , xiv software and hardware requirements , xii

P presentation space , 23 product support , xiv

41

Index

R resolving errors , 24

T trace display , 23 trace display option , 26 troubleshooting configuration errors , 25 troubleshooting nonconfiguration errors , 25 troubleshooting using the trace display utility , 23

42

Tell Us About This Manual

As a user of Silicon Graphics products, you can help us to better understand your needs and to improve the quality of our documentation.

Any information that you provide will be useful. Here is a list of suggested topics:

• General impression of the document

• Omission of material that you expected to find

• Technical errors

• Relevance of the material to the job you had to do

• Quality of the printing and binding

Please send the title and part number of the document with your comments. The part number for this document is 007-1410-020.

Thank you!

Three Ways to Reach Us

• To send your comments by electronic mail, use either of these addresses:

– On the Internet: [email protected]

– For UUCP mail (through any backbone site): [your_site]!sgi!techpubs

• To fax your comments (or annotated copies of manual pages), use this fax number: 650-965-0964

• To send your comments by traditional mail, use this address:

Technical Publications

Silicon Graphics, Inc.

2011 North Shoreline Boulevard, M/S 535

Mountain View, California 94043-1389