CH PW3270 Guida Utente

Version 1.1Windows HLLAPISpecificationGreg Millard Digital Communications Associates, Inc.Sean Grinslade Attachmate CorporationDavid Fuchs Wall Data

cii ContentsWinHLLAPICancelAsyncRequest( )This function cancels an outstanding WinHLLAPIAsync( )-based request.int WinHLLAPICancelAsyncRequest(HANDLE

Contents ciiiWinHLLAPICancelBlockingCall( )This function cancels any outstanding blocking operation for its thread. Any outstanding blocked callcance

civ ContentsWinHLLAPIStartup( )This function allows an application to specify the version of Windows HLLAPI required and to retrievedetails of the sp

Contents cvAppversionsDLLVersionsToWinHLLAPIStartupFromWinHLLAPIStartup Result1.0 1.0 1.0 1.0 use 1.01.0 2.0 1.0 2.0 1.0 use 1.01.0 1.0 2.0 1.0 2.0 u

cvi ContentsWinHLLAPISetBlockingHook( )This function installs a new function which a Windows HLLAPI Implementation should use toimplement blocking HL

Contents cviiWinHLLAPIUnhookBlockingHook( )This function removes any previous blocking hook that has been installed and reinstalls the defaultblockin

cviii ContentsAPPENDIX A/****************************************************************************\*

Contents cix#define FINDFIELDLENGTH 32 /* Find Field Length */#define COPYSTRINGTOFIELD 33 /* Copy String To Field */#define COPY

cx Contents/****** Convert Row or Column values ****************************************/#define WHLL_CONVERT_POSITION 'P'#define WHLL_CONV

Contents cxi/****** Windows HLLAPI Return Codes *****************************************/#define WHLLOK 0 /* Successful */#defin

Contents xiiiWindows CallsThe WinHLLAPI( ) call requires you to specify four parameters in every call and has the followingformat:extern VOID FAR PAS

cxii Contents/****** Windows HLLAPI Extentions Return Codes ******************************/#define WHLLALREADY 0xF000 /* An async call is a

Contents cxiiiAPPENDIX BThis appendix contains the following tables:• 3270 and 5250 Character Attributes.• 3270 and 5250 Character Color Attributes.•

cxiv ContentsCharacter Attributes3270 character attributesBit Position Meaning0-1 Character highlighting00 = Normal 10 = Reverse video01 = Blink 11 =

Contents cxvCharacter Color AttributesBit Position Meaning0-3 Background character colors0000 = Black 0100 = Red0001 = Blue 0101 = Magenta0010 = Gree

cxvi ContentsField Attributes3270 field attributesBit Position Meaning0-1 Both set to 1 (field attribute byte)2 Unprotected/protected0 = Unprotected

Contents cxvii5250 field attributesBit Position Meaning0 Field attribute flag0=Not a field attribute1=Field attribute byte1 Visibility0 = Non-display

cxviii ContentsAPPENDIX CThis appendix lists the WinHLLAPI functions defined in release 1.0 of IBM Extended Services forOS/2 EHLLAPI Programming Refe

Contents cxixAllocate Communications Buffer—Function 123This function allows the application to obtain exclusive control of a memory buffer to be use

cxx ContentsWhen this limit is reached, additional requests to WinHLLAPI will return an 11,indicating that the resource is unavailable.

Contents cxxiConnect Structured Fields—Function 120This function allows an application to establish a connection with a Host session.Prerequisite Fun

xiv ContentsPrerequisite CallsMost Windows HLLAPI functions require a prerequisite callanother function that must be called andsuccessfully complete

cxxii ContentsCode DescriptionWHLLOK The function was successful.WHLLNOTCONNECTED An invalid presentation space was specified.WHLLPARAMETERERROR An i

Contents cxxiiiThe semaphore is set during the connect process because the emulator is in an inbound disabled state.The semaphore is cleared for the

cxxiv ContentsDisconnect Structured Fields—Function 121This function drops the connection between the Windows HLLAPI application and the specifiedses

Contents cxxvFree Communications Buffer—Function 124This function allows the application to release exclusive control of a buffer that is no longer r

cxxvi ContentsGet Request Completion—Function 125This function allows the application to determine the status of a previous asynchronous functionrequ

Contents cxxviiCode DescriptionWHLLOK The function was successful.WHLLNOTCONNECTED An invalid presentation space was specified.WHLLPARAMETERERROR An

cxxviii ContentsThe user specifies whether the application can query of wait for one of the following:u A specific asynchronous function request by s

Contents cxxixIf a nonzero Request ID is supplied, this function checks for the completion of only the functionassociated with the ID.If the return c

cxxx ContentsLock Presentation Space API—Function 60This function allows the application to obtain or release exclusive control of the presentation s

Contents cxxxiLock Window Services API—Function 61This function allows the application to obtain or release exclusive control of the presentation spa

Contents xvFunction (Function Number) Prerequisite Call (Function Number)Stop Close Intercept (43) Start Close Intercept (41)Start Keystroke Intercep

cxxxii ContentsQuery Communication Buffer Size—Function 122This function allows the application to determine the maximum and optimum inbound and outb

Contents cxxxiiibyte. For destination/origin connections, the 8-byte header supplied in the Read or Write structuredfields data buffer is stripped an

cxxxiv ContentsRead Structured Fields—Function 126This function receives structured field data from the host application.If the call specifies asynch

Contents cxxxvParameter DescriptionData String When the A (asynchronous) control option is specified andthe request is successfully completed, the fo

cxxxvi ContentsThe application must correct the situation if one of the following return codes is specified:WHLLTRANCANCL Is returned if the first Re

Contents cxxxviiBytes 8-m are where the structured field messages are returned. The following occurs when the call isreturned:u The word at position

cxxxviii ContentsThe following steps must be completed to determine the outcome of an asynchronous Read StructuredFields (126) function call:u If the

Contents cxxxixStorage Manager—Function 17This function allows your application elementary control of blocks of memory for use with theWindows HLLAPI

cxl ContentsWHLLBLOCKNOTAVAIL You requested more storage than is available.WHLLSYSERROR The function failed due to a system error. Any time resultsar

Contents cxliParameter DescriptionData String NAData Length NAPS Position 03 (QUERYFREESTORAGE)Parameter DescriptionData Length Size of the largest b

xvi ContentsDisconnect Structured Fields (121)Query Communications Buffer Size (122)Allocate Communications Buffer (123)Free Communications Buffer (1

cxlii ContentsWrite Structured Fields—Function 127This function writes structured field data from the Windows HLLAPI application to the hostapplicati

Contents cxliiiBytes 9-10 A 16-bit value representing thedestination/origin ID returned to theapplication by the emulator. Thisfunction request ID is

cxliv ContentsThe application must correct the situation if one of the following return codes is specified:Code DescriptionWHLLTRANCANCL Is returned

Contents cxlvBytes 8-m are where the structured field messages are returned. The following occurs when the call isreturned:u The word at position 2 c

cxlvi ContentsThe following steps must be completed to determine the outcome of an asynchronous Write StructuredFields (127) function call:u If the W

Contents cxlviiAPPENDIX DThis appendix lists and defines the query reply structures supported by the Windows HLLAPIstructured field interface. See th

cxlviii ContentsThe DDM Query ReplySeveral DDM query reply formats will be supported. Some of these formats are listed below:Table D-l. DDM Query Rep

Contents cxlixVERS: The value given in VERS is used to indicate the version of PCLK installed in the terminal atthe time the query reply is returned.

cl ContentsTable D-4. Base DDM Query Reply Format with Name and Direct Access SDPs(continued)Offset Length Content Meaning14 -(13+n) n bytes Name Nam

Contents cliThe SDPs begin at offsets 12 and 16.See the IBM 3270 Information Display System Data Stream Programmer’s Reference for the fielddefinitio

Contents xviiChange Presentation Space Window Name—Function 105This function allows the application to specify a new name for the presentation space

clii Contents1 byte 0x01 Direct Access 13-141 word DOID Destination/OriginID assigned by thesubsystemQUERYThis bit must be set to Binary 1 for all IB

Contents cliiiDirect Access Self-Defining ParameterThis self-defining parameter provides the ID for use in the destination/origin structured field in

cliv ContentsThe OEM Auxiliary Device Query ReplyThe OEM Auxiliary Device Query Reply format is as follows:Table D-9. OEM Auxiliary Device Base Forma

Contents clv2-3 2 bytes VERS Protocol VersionVERS: The value given in VERS is used to indicate the version of PCLK installed in the terminal atthe ti

clvi ContentsThe Cooperative Processing Requester Query ReplyThe Cooperative Processing Requester query reply is also called the SRPI query reply or

Contents clviiThe Product Defined Query ReplyThis query reply is used by IBM products using registered subidentifiers within the X ' 9C ' d

clviii ContentsValid values for REFID (offset 6) and SSID (offset 7) of the Product Defined query reply are asfollows:Table D-14. IBM Product Defined

Contents clixTable D-15. IBM Product Defined Direct Access SDPOffset Length Content Meaning0 1 byte 0x04 Parameter Length1 1 byte 0x03 PCLK ProtocolC

clx ContentsDirect Access Self-Defining ParameterThe presence of the Direct Access ID self defining parameter indicates the auxiliary device may beac

xviii ContentsA string is ended at the first NULL character found. The NULL character overrides the specified stringlength. If the NULL character is

Contents xixConnect Presentation Space — Function 1This function establishes a connection between a specified presentation space (session) on the Hos

xx ContentsConnect Window Services—Function 101This function allows the application to manage the presentation space windows. Only one WindowsHLLAPI

Contents xxiConvert Position / RowCol—Function 99This function converts a Host session presentation space position into row and column values for the

The specification was developed by the companies listed below (collectively, “Developers”). Althoughit is publicly available and is not confidential,

xxii ContentsCopy Field to String—Function 34This function copies the contents of a specified field in the Host session presentation space to a strin

Contents xxiiiPosition in the Host session presentation space is determined by starting in the upper left corner of thescreen display (row 1, column

xxiv ContentsCopy OIA—Function 13This function returns the Host session Operator Information Area (OIA).Prerequisite FunctionsConnect Presentation Sp

Contents xxvThe 5250 OIA image is always returned in ASCII. The 3270 OIA image willbe returned in one of the following states depending on Set Sessio

xxvi ContentsGroup 2: Character selection1 byte (Data String position 83) applies to Data String position 37Bit 0 ReservedBit 1 APLBits 2-7 ReservedG

Contents xxviiGroup 8: Input inhibited5 bytes (Data String positions 89-93) apply to Data String position 10 (except wherenoted)Byte 1 (Data String p

xxviii ContentsGroup 9: PSS group 21 byte (Data String position 94) not used (reserved)Group 10: Highlight group 21 byte (Data String position 95)Bit

Contents xxixOIA Group Indicator Meanings for 5250 SessionsGroup 1: Online and screen ownership1 byte (Data String position 82) applies to Data Strin

xxx ContentsGroup 8: Input inhibited5 bytes (Data String positions 89-93) apply to Data String position 58 (except wherenoted)Byte 1 (Data String pos

Contents xxxiGroup 13: Printer status1 byte (Data String position 98) not used (reserved)Group 14: Graphics1 byte (Data String position 99) not used

5ContentsChapter 1 Introduction 1Windows HLLAPI Overview 1IBM EHLLAPI 1Microsoft Windows Graphical Environment and Windows Specific Extens

xxxii ContentsCopy Presentation Space—Function 5This function copies the contents of the current Host session’s presentation space into a string buff

Contents xxxiiiThis function translates characters from EBCDIC to ASCII. The translation depends on the setting ofthe following session options:Sessi

xxxiv ContentsCopy Presentation Space to String—Function 8This function copies all or part of the Host session presentation space into a string buffe

Contents xxxvPS Position in the Host session presentation space is determined by starting in the upper left corner ofthe screen display (row 1, colum

xxxvi ContentsCopy String to Field—Function 33This function copies a string into the specified field in the Host session presentation space.Prerequis

Contents xxxviiCopy String to Presentation Space—Function 15This function copies an ASCII string directly to a specified position in the Host session

xxxviii ContentsDisconnect Presentation Space—Function 2This function disconnects a Host session from your Windows HLLAPI session.Prerequisite Functi

Contents xxxixDisconnect Window Services—Function 102This function disconnects window services between a Windows HLLAPI application and a specifiedWi

xl ContentsFind Field Length—Function 32This function determines the length of a specified field in the Host session presentation space. You canuse F

Contents xliCode DescriptionWHLLOK The specified field length was found.WHLLNOTCONNECTED Your Windows HLLAPI application is not currentlyconnected to

6 Windows HLLAPI FunctionsQuery Close Intercept—Function 42 43Query Cursor Location—Function 7 44Query Field Attribute—Function 14 45Query H

xlii ContentsFind Field Position—Function 31This function determines the starting position of a field in the Host session presentation space. You can

Contents xliiiCode DescriptionWHLLOK The specified field was found.WHLLNOTCONNECTED Your Windows HLLAPI application is not currentlyconnected to a Ho

xliv ContentsGet Key—Function 51This function allows your Windows HLLAPI application to intercept keystrokes from Host sessionsthat have keystroke in

Contents xlvCode DescriptionWHLLUNDEFINEDKEY The user entered an invalid key combination for this Hostsession presentation space.WHLLNOKEYSTROKES The

xlvi ContentsPause—Function 18This function causes your application to wait for a specified amount of time.Prerequisite FunctionsNone.WinHLLAPI(PAUSE

Contents xlviiPost Intercept Status—Function 52This function notifies WinHLLAPI that a keystroke obtained with Get Key (function 51) has beenaccepted

xlviii ContentsQuery Close Intercept—Function 42This function allows the application to determine if the user selected to close the emulator program.

Contents xlixQuery Cursor Location—Function 7This function determines the location of the cursor in the Host session presentation space.Prerequisite

l ContentsQuery Field Attribute—Function 14This function returns the attribute byte of the field containing the specified position in the Host sessio

Contents liQuery Host Update—Function 24This function determines if the presentation space, Operator Information Area (OIA), or both, of thespecified

Chapter 1 Introduction 7NOKEY/KEY$nnnnnnnn 77Start Close Intercept—Function 41 78Start Host Notification—Function 23 80Start Keystroke In

lii ContentsQuery Session Status—Function 22This function accesses the status of a specified session.Prerequisite FunctionsNone.WinHLLAPI(QUERYSESSIO

Contents liiiBytes 12-13 Number of rows in the Host sessionpresentation space. This is a binarynumber, not ASCII. If the session type is“E” or “G” (p

liv ContentsQuery Sessions—Function 10This function returns the number of Host screen sessions that are active, and a string containinginformation on

Contents lvQuery System—Function 20This function determines the level and version of WHLLAPI under which your Windows HLLAPIapplication is running.Pr

lvi ContentsQuery Window Coordinates—Function 103This function requests the window coordinates for a presentation space.Prerequisite FunctionsConnect

Contents lviiReceive File—Function 91This function transfers a file from the Host to the PC running the Windows HLLAPI application. Thefile transfer

lviii ContentsThis function is affected by the session options STRLEN/STREOT, EOT=c, QUIET/NOQUIET, andTIMEOUT=0/TIMEOUT=c. See Set Session Parameter

Contents lixRelease—Function 12This function releases the currently Connected Host session presentation space locked with Reserve(function 11).Prereq

lx ContentsReserve—Function 11This function reserves the currently Connected Host session presentation space, locking out the userand preventing keyb

Contents lxiReset System—Function 21This function reinitializes the system to its default (start) state:u All session options are reset to their defa

8 Windows HLLAPI FunctionsLock Window Services API—Function 61 132Query Communication Buffer Size—Function 122 133Read Structured Fields—Functi

lxii ContentsSearch Field—Function 30This function searches a field in the Host session presentation space for the specified string. You canuse Searc

Contents lxiiiPosition in the Host session presentation space is determined by starting in the upper left corner of thescreen display (row 1, column

lxiv ContentsSearch Presentation Space—Function 6This function allows you to search the Host session presentation space for a specified string.Prereq

Contents lxvThis function is affected by four session option parameters: STRLEN/STREOT, EOT=c,SRCHALL/SRCHFROM and SRCHFRWD/SRCHBKWD. See Set Session

lxvi ContentsSend File—Function 90This function transfers a file from the PC running the Windows HLLAPI application to the Host. Thefile transfer can

Contents lxviiThis function is affected by the session options STRLEN/STREOT, EOT=c, QUIET/NOQUIET, andTIMEOUT=0/TIMEOUT=c . See Set Session Paramete

lxviii ContentsSend Key—Function 3This function sends one or more keystrokes (up to a maximum of 255) to the connected Host session.The keystrokes ap

Contents lxixpart of the Data String parameters. The Escape character can be changed with the session optionESC=c. See Set Session Parameters (functi

lxx ContentsHexadecimal @A@X XHome @0 (zero) X XInsert @I X7 XInsert Toggle @A@I XHost Print @P XLeft Tab (Back Tab) @B X XNew Line @N X XPage Up @u

Contents lxxiPF9/F9 @9 X XPF10/F10 @a X XPF11/F11 @b X XPF12/F12 @c X XPF13 @d X XPF14 @e X XPF15 @f X XPF16 @g X XPF17 @h X XPF18 @i X XPF19 @j X XP

Chapter 1 Introduction 9CHAPTER 1Windows HLLAPI OverviewWindows™ HLLAPI defines a standard and consistent IBM® EHLLAPI-style API for the 16- and32

lxxii ContentsSet Cursor—Function 40This function places the cursor at a specified position in the Host session presentation space.Prerequisite Funct

Contents lxxiiiSet Session Parameters—Function 9This function sets the options of the Host session. Session options that are not set with this functi

lxxiv ContentsThe following table lists the functions that are affected by session options, and the session options thataffect them.Function Name(fun

Contents lxxvFunction Name(function number) Session OptionsGet Key (function 51) ESC=c, TWAIT/LWAIT/NWAITSend File (function 90) STRLEN/STREOT, EOT=

lxxvi ContentsSRCHALL/SRCHFROMDetermine how the Host session presentation space is to be searched. Applies to Search PresentationSpace (6) and Search

Contents lxxviiFPAUSE/IPAUSEDetermine the type of pause to use. Applies to Pause (18).Session Option DescriptionFPAUSE Full pause; pause for the leng

lxxviii ContentsSession Option DescriptionTIMEOUT=c Set the timeout to a specific period. A CTRL+BREAK is issuedautomatically after the specified per

Contents lxxixTWAIT/LWAIT/NWAITDetermine the characteristics of a wait period. Applies to Wait (4) and Get Key(51).Session Option DescriptionTWAIT Fo

lxxx ContentsXLATE/NOXLATEDetermine the translation of extended attributes (EABs). Applies to Copy Presentation Space (5), CopyPresentation Space to

Contents lxxxiWRITE_SUPER/WRITE_WRITE/WRITE_READ/WRITE_NONE/SUPER_WRITE/READ_WRITESpecify whether a Windows HLLAPI application can or will share the

10 Windows HLLAPI FunctionsCHAPTER 2WinHLLAPI Installation CheckingTo detect the presence of any Windows HLLAPI implementations on a system, an appli

lxxxii ContentsNOKEY/KEY$nnnnnnnnAllow applications that have sharing requirements to limit access to a partner application (i.e. anapplication devel

Contents lxxxiiiStart Close Intercept—Function 41This function allows the application to intercept user requests to close the emulation program.Prere

lxxxiv ContentsAsynchronous ModeWhen asynchronous mode is enabled by calling WinHLLAPIAsync, the function initiates closeintercept and immediately re

Contents lxxxvStart Host Notification—Function 23This function enables notifying your Windows HLLAPI application of changes in the Host sessionpresen

lxxxvi ContentsOnce enabled, Host notification is enabled until you call Stop Host Notification (function 25).Once you call this function, you can us

Contents lxxxviiStart Keystroke Intercept—Function 50This function enables your Windows HLLAPI application to intercept keystrokes sent to a session

lxxxviii ContentsIf position 2 of Data String is “D,” only AID keystrokes are intercepted. All other keystrokes arepassed on to the appropriate Host

Contents lxxxixStop Close Intercept—Function 43This function stops the application from intercepting close requests from the user. Subsequent closere

xc ContentsStop Host Notification—Function 25This function disables notifying your Windows HLLAPI application of changes in the Host sessionpresentat

Contents xciStop Keystroke Intercept—Function 53This function disables the ability of your Windows HLLAPI application to intercept keystrokes.Prerequ

Chapter 3 Windows HLLAPI Functions 11CHAPTER 3Windows HLLAPI functions are requested using the appropriate parameter within the WinHLLAPI( )call,

xcii ContentsWait—Function 4This function determines whether the Host session is in a wait state. If, for some reason, the session isin a wait state,

Contents xciiiAlthough both APIs are supported, you should use WinHLLAPIAsync instead of WinHLLAPIwhenever possible. Note that if NWAIT is specified,

xciv ContentsWindow Status—Function 104This function allows the application to query or change a session’s window size, location, or visiblestate, or

Contents xcvData String DescriptionSet window status - a 16-byte string with the following format:u WHLL_WINDOWSTATUS_MAXIMIZE. Set the window tom

xcvi ContentsData String DescriptionQuery extended window status - a 20-byte string with the following format:Byte 1 Short name session ID of the des

Contents xcviiCode DescriptionWHLLOK The function was successful.WHLLNOTCONNECTEDAn invalid presentation space was specified, or was notconnected for

xcviii ContentsCHAPTER 4This chapter describes API extensions to Windows HLLAPI that allow asynchronous communication.These extensions have been desi

Contents xcixWinHLLAPIAsync( )This function provides an asynchronous flavor to the following HLLAPI functions:STARTKSINTERCEPT, WAIT, STARTHOSTNOTIFI

c ContentsWinHLLAPICleanup( )This routine should be called by an application to deregister itself from a Windows HLLAPIimplementation.BOOL WinHLLAPIC

Contents ciWinHLLAPIIsBlocking( )This function allows a task to determine if it is executing while waiting for a previous blocking call tocomplete.BO