Windows HLLAPI Specification Version 1.1 Greg Millard Sean Grinslade David Fuchs Preston Sights Michael Lee Gordon Mangione Digital Communications Associates, Inc.
The specification was developed by the companies listed below (collectively, “Developers”). Although it is publicly available and is not confidential, the specification is still protected by copyright laws. Additional copies of the specification can be obtained on the MSDR forum on CompuServe® Information Services in Library 2. This document is for informational purposes only. THE DEVELOPERS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.
5 Contents Chapter 1 Introduction 1 Windows HLLAPI Overview 1 IBM EHLLAPI 1 Microsoft Windows Graphical Environment and Windows Specific Extensions 2 Chapter 2 Programming with Windows HLLAPI 3 WinHLLAPI Installation Checking 3 Byte Ordering 3 Deviation from IBM EHLLAPI 3 Window Handle Passed for Each Async Call 4 Pointers 4 Blocking Routines 4 Chapter 3 Windows HLLAPI Functions 5 Windows Calls 6 Prerequisite Calls 7 5250 Emulation Support 8 Change Presentation Space Window Name—Function 105 10 Connect Pre
6 Windows HLLAPI Functions Query Close Intercept—Function 42 43 Query Cursor Location—Function 7 44 Query Field Attribute—Function 14 45 Query Host Update—Function 24 46 Query Session Status—Function 22 47 Query Sessions—Function 10 49 Query System—Function 20 50 Query Window Coordinates—Function 103 51 Receive File—Function 91 52 Asynchronous Mode 53 Release—Function 12 54 Reserve—Function 11 55 Reset System—Function 21 56 Search Field—Function 30 57 Search Presentation Space—Function 6 59 Send File—Func
Chapter 1 Introduction NOKEY/KEY$nnnnnnnn 77 Start Close Intercept—Function 41 78 Start Host Notification—Function 23 80 Start Keystroke Intercept—Function 50 82 Stop Close Intercept—Function 43 84 Stop Host Notification—Function 25 85 Stop Keystroke Intercept—Function 53 86 Wait—Function 4 87 Window Status—Function 104 89 Chapter 4 Extensions for the Windows Environment 93 WinHLLAPIAsync( ) 94 Windows HLLAPI Supplier Notes 94 WinHLLAPICleanup( ) 95 Windows HLLAPI Supplier Notes 95 WinHLLAPIIsBlocking( ) 9
8 Windows HLLAPI Functions Lock Window Services API—Function 61 132 Query Communication Buffer Size—Function 122 133 Read Structured Fields—Function 126 135 Storage Manager—Function 17 140 Get Storage 141 Free Storage 141 Free All Storage 142 Query Free Storage 142 Write Structured Fields—Function 127 143 Appendix D Query Reply Data Structures for Windows HLLAPI 149 The DDM Query Reply 150 DDM Application Name Self-Defining Parameter 150 PCLK Protocol Controls Self-Defining Parameter 151 Base DDM Query Re
Chapter 1 Introduction C H A P T E R 9 1 Introduction Windows HLLAPI Overview Windows™ HLLAPI defines a standard and consistent IBM® EHLLAPI-style API for the 16- and 32-bit versions of the Microsoft® Windows graphical environment. It encompasses both familiar IBM EHLLAPI-style routines and a set of Windows-specific extensions designed to allow the programmer to take advantage of the message-driven nature of the Windows graphical environment.
10 Windows HLLAPI Functions C H A P T E R 2 Programming with Windows HLLAPI WinHLLAPI Installation Checking To detect the presence of any Windows HLLAPI implementations on a system, an application that has been linked with the Windows HLLAPI Import Library can attempt to call the WinHLLAPIStartup( ) routine. Alternately, an application can examine the $PATH environment variable to search for instances of Windows HLLAPI API implementations (WHLLAPI.DLL).
Chapter 3 Windows HLLAPI Functions C H A P T E R 11 3 Windows HLLAPI Functions Windows HLLAPI functions are requested using the appropriate parameter within the WinHLLAPI( ) call, and by specifying the function constant (or number equivalent) and the call parameters specific to that function. This chapter details the supported Windows HLLAPI functions, describing each function and their corresponding parameters and return codes.
Contents Windows Calls The WinHLLAPI( ) call requires you to specify four parameters in every call and has the following format: extern VOID FAR PASCAL WinHLLAPI( ) Call Parameter Definitions LPWORD lpwFunction, /* Function name */ LPBYTE lpbyString, /* String pointer */ LPWORD lpwLength, /* String (data) length */ LPWORD lpwReturnCode ); /* Return code */ The parameters used in the WinHLLAPI function calls are: Parameter Description lpwFunction A pointer to the defined function name of the
xiv Contents Prerequisite Calls Most Windows HLLAPI functions require a prerequisite callanother function that must be called and successfully completed before the desired call can be issued. The following table lists the Windows HLLAPI functions and their prerequisite calls. “None” indicates that the function has no prerequisite call.
Contents Function (Function Number) Prerequisite Call (Function Number) Stop Close Intercept (43) Start Close Intercept (41) Start Keystroke Intercept (50) None Get Key (51) Start Keystroke Intercept (50) Post Intercept Status (52) Start Keystroke Intercept (50) Stop Keystroke Intercept (53) Start Keystroke Intercept (50) Send File (90) None Receive File (91) None Convert Position / RowCol (99) None Connect Window Services (101) None Disconnect Window Services (102) Connect Window Servi
xvi Contents Disconnect Structured Fields (121) Query Communications Buffer Size (122) Allocate Communications Buffer (123) Free Communications Buffer (124) Get Request Completion (125) Read Structured Fields (126) Write Structured Fields (127)
Contents xvii Change Presentation Space Window Name— Function 105 This function allows the application to specify a new name for the presentation space window or reset the presentation space window to the default name. Prerequisite Functions Connect Window Services (function 101).
xviii Remarks Contents A string is ended at the first NULL character found. The NULL character overrides the specified string length. If the NULL character is not at the end of the specified length, the last byte at the specified length is replaced by a NULL character and the remainder of the Data String is lost. If the NULL character is found before the specified length, the string is truncated at that point and the remainder of the Data String is lost. This function is not supported for 5250 emulation.
Contents xix Connect Presentation Space — Function 1 This function establishes a connection between a specified presentation space (session) on the Host and your Windows HLLAPI application. Prerequisite Functions None. Function Call WinHLLAPI(CONNECTPS,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String One-character short name session ID of the Host session to connect with, either an upper- or lower-case letter. Data Length NA (defaults to 1).
xx Contents Connect Window Services—Function 101 This function allows the application to manage the presentation space windows. Only one Windows HLLAPI application at a time can be connected to a presentation space for window services. Prerequisite Functions None. Function Call WinHLLAPI(CONNECTWINDOWSERVICES,lpbyString, lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String One-character short name session ID of the presentation space. Data Length NA (defaults to 1).
Contents xxi Convert Position / RowCol—Function 99 This function converts a Host session presentation space position into row and column values for the PC display or converts PC display row and column values into a Host session presentation space position. Prerequisite Functions None. Function Call WinHLLAPI(CONVERT,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String A 2-byte string.
xxii Contents Copy Field to String—Function 34 This function copies the contents of a specified field in the Host session presentation space to a string. You can use Copy Field to String for either protected or unprotected fields. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(COPYFIELDTOSTRING,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String Buffer to hold the copied field.
Contents Remarks xxiii Position in the Host session presentation space is determined by starting in the upper left corner of the screen display (row 1, column 1). At the end of each screen display row, the next Host session presentation space position is column 1 of the following screen display row. This process continues until the end of the Host session presentation space (screen display) is reached.
xxiv Contents Copy OIA—Function 13 This function returns the Host session Operator Information Area (OIA). Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(COPYOIA,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String String buffer to hold the OIA. Must be defined for at least 103 bytes. Data Length Length of Data String in characters.
Contents xxv Note The 5250 OIA image is always returned in ASCII. The 3270 OIA image will be returned in one of the following states depending on Set Session Parameter (9): OLDOIA OIA image returned in 3270 PC format. NEWOIA OIA image returned in ASCII format.
xxvi Contents Group 2: Character selection 1 byte (Data String position 83) applies to Data String position 37 Bit 0 Reserved Bit 1 APL Bits 2-7 Reserved Group 3: Shift state 1 byte (Data String position 84) applies to Data String position 43 Bit 0 Upper shift Bit 1 Numeric Bits 2-7 Reserved Group 4: PSS group 1 1 byte (Data String position 85) not used (reserved) Group 5: Highlight group 1 1 byte (Data String position 86) applies to Data String position 48 Bit 0 User-selectable Bit 1 Field
Contents Group 8: Input inhibited 5 bytes (Data String positions 89-93) apply to Data String position 10 (except where noted) Byte 1 (Data String position 89) Bit 0 Non-resetable machine check Bit 1 Reserved Bit 2 Machine check Bit 3 Communications check Bit 4 Program check Bit 5 Reserved Bit 6 Device not working Bit 7 Reserved Byte 2 (Data String position 90) Bit 0 OIA time Bit 1 Terminal wait Bit 2 Reserved Bit 3 Minus function Bit 4 Too much entered Bits 5-7 Reserved Byte 3 (D
xxviii Contents Group 9: PSS group 2 1 byte (Data String position 94) not used (reserved) Group 10: Highlight group 2 1 byte (Data String position 95) Bit 0 Selected Bit 1-7 Reserved Group 11: Color group 2 1 byte (Data String position 96) Bit 0 Selected Bit 1-7 Reserved Group 12: Communication error reminder applies to Data String position 23 1 byte (Data String position 97) Bit 0 Communications error Bit 1-7 Reserved Group 13: Printer status applies to Data String position 62 1 byte (Data Str
Contents OIA Group Indicator Meanings for 5250 Sessions Group 1: Online and screen ownership 1 byte (Data String position 82) applies to Data String position 19 Bits 0-2 Reserved Bit 3 System available Bit 4 Reserved Bit 5 Subsystem ready Bits 6-7 Reserved Group 2: Character selection 1 byte (Data String position 83) applies to Data String position 44 Bits 0-4 Reserved Bit 5 Diacritic mode Bit 6-7 Reserved Group 3: Shift state 1 byte (Data String position 84) applies to Data String position
xxx Contents Group 8: Input inhibited 5 bytes (Data String positions 89-93) apply to Data String position 58 (except where noted) Byte 1 (Data String position 89) Bit 0-7 Reserved Byte 2 (Data String position 90) Bit 0-7 Reserved Byte 3 (Data String position 91) Bits 0-4 Reserved Bit 5 User input error (II) Bits 3-7 Reserved Byte 4 (Data String position 92) Bits 0-1 Reserved Bit 2 System wait Bits 3-7 Reserved Byte 5 (Data String position 93) Bits 0-7 Reserved Bit 5 User input error (II)
Contents Group 13: Printer status 1 byte (Data String position 98) not used (reserved) Group 14: Graphics 1 byte (Data String position 99) not used (reserved) Group 15: Not used 1 byte (Data String position 100) not used (reserved) Group 16: Autokey play/record status 1 byte (Data String position 101) not used (reserved) Group 17: Autokey abort/pause status 1 byte (Data String position 102) not used (reserved) Group 18: Enlarge state 1 byte (Data String position 103) not used (reserved) xxxi
xxxii Contents Copy Presentation Space—Function 5 This function copies the contents of the current Host session’s presentation space into a string buffer. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(COPYPS,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String String that will contain the Host session presentation space. The string length must be defined as the maximum size of the presentation space.
Contents xxxiii This function translates characters from EBCDIC to ASCII. The translation depends on the setting of the following session options: Session Option Effect on this Function NOATTRB Unknown values are translated into spaces. ATTRB Unknown values are copied untranslated. NOEAB Extended attribute bytes are not passed to the string. EAB, XLATE Extended attribute bytes are passed and translated into CGA colors. EAB, NOXLATE Extended attribute bytes are returned.
xxxiv Contents Copy Presentation Space to String—Function 8 This function copies all or part of the Host session presentation space into a string buffer. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(COPYPSTOSTR,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String String that will contain the specified portion of the Host session presentation space.
Contents Remarks xxxv PS Position in the Host session presentation space is determined by starting in the upper left corner of the screen display (row 1, column 1). At the end of each screen display row, the next Host session presentation space position is column 1 of the following screen display row. This process continues until the end of the Host session presentation space (screen display) is reached.
xxxvi Contents Copy String to Field—Function 33 This function copies a string into the specified field in the Host session presentation space. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(COPYSTRINGTOFIELD,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String String to copy to the specified field. Data Length Number of characters. NA if session option EOT is specified.
Contents xxxvii Copy String to Presentation Space—Function 15 This function copies an ASCII string directly to a specified position in the Host session presentation space. Prerequisite Functions Connect Presentation Space (function 1) Function Call WinHLLAPI(COPYSTRTOPS,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String String of ASCII data to copy to the Host session presentation space. Data Length Number of characters. NA if session option EOT is specified.
xxxviii Contents Disconnect Presentation Space—Function 2 This function disconnects a Host session from your Windows HLLAPI session. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(DISCONNECTPS,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String NA Data Length NA PS Position NA Code Description WHLLOK The disconnect is successful.
Contents xxxix Disconnect Window Services—Function 102 This function disconnects window services between a Windows HLLAPI application and a specified Windows HLLAPI session. Prerequisite Functions Connect Window Services (function 101). Function Call WinHLLAPI(DISCONNECTWINDOWSERVICES,lpbyString, lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String One-character short name session ID of the presentation space. Data Length NA (defaults to 1).
xl Contents Find Field Length—Function 32 This function determines the length of a specified field in the Host session presentation space. You can use Find Field Length for either protected or unprotected fields but only in a field-formatted host presentation space. Prerequisite Functions Connect Presentation Space (function 1).
Contents Return Codes Remarks Code Description WHLLOK The specified field length was found. WHLLNOTCONNECTED Your Windows HLLAPI application is not currently connected to a Host session. WHLLPARAMETERERROR One or more of the call parameters are invalid. WHLLPOSITIONERROR PS Position is invalid. WHLLSYSERROR The function failed due to a system error. WHLLNOFIELD The specified field was not found, or the Host session presentation space is unformatted.
xlii Contents Find Field Position—Function 31 This function determines the starting position of a field in the Host session presentation space. You can use Find Field Position for either protected or unprotected fields but only in a field-formatted host presentation space. Prerequisite Functions Connect Presentation Space (function 1).
Contents Return Codes Remarks Code Description WHLLOK The specified field was found. WHLLNOTCONNECTED Your Windows HLLAPI application is not currently connected to a Host session. WHLLPARAMETERERROR One or more of the call parameters are invalid. WHLLPOSITIONERROR PS Position is invalid. WHLLSYSERROR The function failed due to a system error. WHLLNOFIELD The specified field was not found, or the Host session presentation space is unformatted.
xliv Contents Get Key—Function 51 This function allows your Windows HLLAPI application to intercept keystrokes from Host sessions that have keystroke intercept enabled, and to process those keystrokes. Prerequisite Functions Start Keystroke Intercept (function 50).
Contents Remarks xlv Code Description WHLLUNDEFINEDKEY The user entered an invalid key combination for this Host session presentation space. WHLLNOKEYSTROKES There are no keystrokes available in the keystroke queue. WHLLKEYOVERFLOW The keystroke queue has overflowed and keystroke(s) were lost. This function is affected by the session options ESC=c and NWAIT/LWAIT/TWAIT. See Set Session Parameters (function 9) for details.
xlvi Contents Pause—Function 18 This function causes your application to wait for a specified amount of time. Prerequisite Functions None. Function Call WinHLLAPI(PAUSE,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String NA Data Length Amount of time to pause in multiples of 0.5 seconds. For example, a value of 240 signifies 2 minutes (120 seconds). PS Position NA Code Description WHLLOK Pause completed (specified wait time has expired).
Contents xlvii Post Intercept Status—Function 52 This function notifies WinHLLAPI that a keystroke obtained with Get Key (function 51) has been accepted or rejected. If rejected, a beep is generated. Prerequisite Functions Start Keystroke Intercept (function 50).
xlviii Contents Query Close Intercept—Function 42 This function allows the application to determine if the user selected to close the emulator program. Prerequisite Functions Start Close Intercept (function 41). Function Call WinHLLAPI(QUERYCLOSEINTERCEPT,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String One-character short name session ID of the presentation space. Data Length Must be specified.
Contents xlix Query Cursor Location—Function 7 This function determines the location of the cursor in the Host session presentation space. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(QUERYCURSORLOC,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String NA Data Length NA PS Position NA Parameter Description lpwLength Data Length: the position of the cursor in the Host session presentation space.
l Contents Query Field Attribute—Function 14 This function returns the attribute byte of the field containing the specified position in the Host session presentation space. Prerequisite Functions Connect Presentation Space (function 1).
Contents li Query Host Update—Function 24 This function determines if the presentation space, Operator Information Area (OIA), or both, of the specified Host session have been updated since one of the following occurs: u Start Host Notification (function 23) was called. u The previous call of this function. Prerequisite Functions Start Host Notification (function 23).
lii Contents Query Session Status—Function 22 This function accesses the status of a specified session. Prerequisite Functions None. Function Call WinHLLAPI(QUERYSESSIONSTATUS,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String 18-byte string for returned session information; first byte is a short name session ID of the session to query, or space or null for the current session.
Contents Bytes 12-13 Parameter Return Codes Remarks liii Number of rows in the Host session presentation space. This is a binary number, not ASCII. If the session type is “E” or “G” (printers), the value is binary zero. Description Bytes 14-15 Number of columns in the Host session presentation space. This is a binary number, not ASCII. If the session type is “E” or “G” (printers), the value is binary zero. Bytes 16-17 Host code page number, expressed as a binary number. Byte 18 Reserved.
liv Contents Query Sessions—Function 10 This function returns the number of Host screen sessions that are active, and a string containing information on each of the Host screen sessions. Host printer sessions are not supported. Prerequisite Functions None. Function Call WinHLLAPI(QUERYSESSIONS,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String String buffer to hold the information string. Must be defined as 12*(number of active Host sessions) bytes.
Contents Query System—Function 20 This function determines the level and version of WHLLAPI under which your Windows HLLAPI application is running. Prerequisite Functions None. Function Call WinHLLAPI(QUERYSYSTEM,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String Buffer for query data, must be defined for 35 bytes. Data Length NA (length of 35 is implied).
lvi Contents Query Window Coordinates—Function 103 This function requests the window coordinates for a presentation space. Prerequisite Functions Connect Window Services (function 101). Function Call WinHLLAPI(QUERYWINDOWCOORDINATES,lpbyString, lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String 17-byte string for returned session information; first byte is a short name session ID of the session to query, or space or null for the current session.
Contents lvii Receive File—Function 91 This function transfers a file from the Host to the PC running the Windows HLLAPI application. The file transfer can be synchronous (dedicated) or asynchronous (call-and-return). See the “Remarks” section for information on asynchronous file transfer. Prerequisite Functions None.
lviii Remarks Contents This function is affected by the session options STRLEN/STREOT, EOT=c, QUIET/NOQUIET, and TIMEOUT=0/TIMEOUT=c. See Set Session Parameters (function 9) for details. You cannot use this function on 5250 sessions, 5250 printer sessions, and 3270 printer sessions. Only one file transfer operation is supported at a time, regardless of the number of Host sessions accessed by your Windows HLLAPI application.
Contents lix Release—Function 12 This function releases the currently Connected Host session presentation space locked with Reserve (function 11). Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(RELEASE,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String NA Data Length NA PS Position NA Code Description WHLLOK The Host session presentation space has been released (unlocked).
lx Contents Reserve—Function 11 This function reserves the currently Connected Host session presentation space, locking out the user and preventing keyboard input. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(RESERVE,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String NA Data Length NA PS Position NA Code Description WHLLOK The Host session presentation space has been reserved (locked).
Contents lxi Reset System—Function 21 This function reinitializes the system to its default (start) state: u All session options are reset to their defaults. u Event notification is stopped. u Any reserved sessions are released. u Connected sessions are disconnected. u The current status of Host sessions is updated. Prerequisite Functions None.
lxii Contents Search Field—Function 30 This function searches a field in the Host session presentation space for the specified string. You can use Search Field for either protected or unprotected fields but only in a field-formatted host presentation space. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(SEARCHFIELD,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String String to search for.
Contents Remarks lxiii Position in the Host session presentation space is determined by starting in the upper left corner of the screen display (row 1, column 1). At the end of each screen display row, the next Host session presentation space position is column 1 of the following screen display row. This process continues until the end of the Host session presentation space (screen display) is reached.
lxiv Contents Search Presentation Space—Function 6 This function allows you to search the Host session presentation space for a specified string. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(SEARCHPS,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String String to search for. Data Length Length of the search string. NA if session option EOT is specified. PS Position Position in the Host session presentation space.
Contents lxv This function is affected by four session option parameters: STRLEN/STREOT, EOT=c, SRCHALL/SRCHFROM and SRCHFRWD/SRCHBKWD. See Set Session parameters (function 9) for details on these session options.
lxvi Contents Send File—Function 90 This function transfers a file from the PC running the Windows HLLAPI application to the Host. The file transfer can be synchronous (dedicated) or asynchronous (call-and-return). See the “Remarks” section for information on asynchronous file transfer. Prerequisite Functions None.
Contents Remarks lxvii This function is affected by the session options STRLEN/STREOT, EOT=c, QUIET/NOQUIET, and TIMEOUT=0/TIMEOUT=c . See Set Session Parameters (function 9) for details. You cannot use this function on 5250 sessions, 5250 printer sessions, or 3270 printer sessions. Only one file transfer operation is supported at a time, regardless of the number of Host sessions accessed by your Windows HLLAPI application.
lxviii Contents Send Key—Function 3 This function sends one or more keystrokes (up to a maximum of 255) to the connected Host session. The keystrokes appear to the session as if they are entered by a user. The keystrokes can include host function keys and AID keys. Prerequisite Functions Connect Presentation Space (function 1).
Contents lxix part of the Data String parameters. The Escape character can be changed with the session option ESC=c. See Set Session Parameters (function 9) for details. When the Data String contains AID keys, the string includes characters up to, and including, the first AID key encountered. The segment string and segment length are set internally to the proper values as the segment is sent to the Host.
lxx Contents Hexadecimal @A@X Home @0 (zero) X X X Insert @I X7 X Insert Toggle @A@I X Host Print @P X Left Tab (Back Tab) @B X X New Line @N X X Page Up @u X Page Down @v X Print (PC) @A@t X Record Backspace @A@< Reset @R X X Right Tab (Tab) @T X X Shift @S X Sys Request @A@H X X Tab (Right Tab) @T X X Test @A@C PA1 @x X PA2 @y X PA3 @z X Meaning Mnemonic 3270 PA4 @+ X PA5 @% X PA6 @& X PA7 @’ X PA8 @( X PA9 @) X PA10 @
Contents PF9/F9 @9 X X PF10/F10 @a X X PF11/F11 @b X X PF12/F12 @c X X PF13 @d X X PF14 @e X X PF15 @f X X PF16 @g X X PF17 @h X X PF18 @i X X PF19 @j X X PF20 @k X X PF21 @l X X PF22 @m X X PF23 @n X X PF24 @o X X lxxi Note If you want to use the “at” sign (@) in the Data String, you must use the twobyte code “@@”.
lxxii Contents Set Cursor—Function 40 This function places the cursor at a specified position in the Host session presentation space. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(SETCURSOR,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String NA. Data Length NA. PS Position Position in the Host session presentation space to locate the cursor.
Contents lxxiii Set Session Parameters—Function 9 This function sets the options of the Host session. Session options that are not set with this function use their default values. Session options set with this function remain in effect until one of the following occurs: u Another Set Session Parameters call sets a new value. u Reset System (function 21) is called. Prerequisite Functions None.
lxxiv Remarks Contents The following table lists the functions that are affected by session options, and the session options that affect them.
Contents Function Name (function number) lxxv Session Options Get Key (function 51) Send File (function 90) Receive File (function 91) Connect PM Window Service (function 101) ESC=c, TWAIT/LWAIT/NWAIT STRLEN/STREOT, EOT=c, NOQUIET/QUIET, TIMEOUT=0/TIMEOUT=c STRLEN/STREOT, EOT=c, NOQUIET/QUIET, TIMEOUT=0/TIMEOUT=c WRITE_SUPER/WRITE_WRITE /WRITE_READ/WRITE_NONE /SUPER_WRITE/READ_WRITE The session options are described on the following pages, grouped by function.
lxxvi Contents SRCHALL/SRCHFROM Determine how the Host session presentation space is to be searched. Applies to Search Presentation Space (6) and Search Field (30). Session Option Description SRCHALL If using Search Presentation Space (6), search the entire Host session presentation space. If using Search Field (30), search the entire field. SRCHALL is the default setting.
Contents lxxvii FPAUSE/IPAUSE Determine the type of pause to use. Applies to Pause (18). Session Option Description FPAUSE Full pause; pause for the length of time specified in Pause (function 18). FPAUSE is the default setting. IPAUSE Interruptible pause; once a Start Host Notification (function 23) call is made, any Host event ends the pause. NOQUIET/QUIET Determine whether the file transfer functions SEND FILE (90) and RECEIVE FILE (91) will generate messages displayed to the user.
lxxviii Contents Session Option Description TIMEOUT=c Set the timeout to a specific period. A CTRL+BREAK is issued automatically after the specified period. There must not be a space on either side of the equal sign; c is a one-byte character that can be only one of the following values: 1 2 3 4 5 6 7 8 9 J K L M N 30 seconds (0.5 minutes) 60 seconds (1.0 minutes) 90 seconds (1.5 minutes) 120 seconds (2.0 minutes) 150 seconds (2.5 minutes) 180 seconds (3.0 minutes) 210 seconds (3.
Contents lxxix TWAIT/LWAIT/NWAIT Determine the characteristics of a wait period. Applies to Wait (4) and Get Key(51). Session Option Description TWAIT For Wait (4), wait up to 60 seconds before timing out on XCLOCK or XSYSTEM. For Get Key (function 51), wait until a keystroke is queued before returning. TWAIT is the default setting. LWAIT For Wait (4), wait until the XCLOCK or XSYSTEM clears.
lxxx Contents XLATE/NOXLATE Determine the translation of extended attributes (EABs). Applies to Copy Presentation Space (5), Copy Presentation Space to String (8) and Copy Field to String (34). Session Option Description XLATE Translate extended attributes (EABs) into CGA colors. NOXLATE Do not translate extended attributes (EABs). CONLOG/CONPHYS Specify which application will be the foreground application when connecting to a session. Applies to Connect Presentation Space (1).
Contents lxxxi WRITE_SUPER/WRITE_WRITE/WRITE_READ /WRITE_NONE/SUPER_WRITE/READ_WRITE Specify whether a Windows HLLAPI application can or will share the presentation space to which it is connected with another application using Connect Presentation Space (1) and Connect PM Window Services (101). Session Option Description WRITE_SUPER Set by a Windows HLLAPI application that requires write access and allows only supervisory applications to connect to its presentation space.
lxxxii Contents NOKEY/KEY$nnnnnnnn Allow applications that have sharing requirements to limit access to a partner application (i.e. an application developed to work with it). Session Option Description NOKEY Allows the application to be compatible with existing applications that do not specify the KEY parameter. KEY$nnnnnnn Specify the keyword to restrict sharing of the presentation space. The keyword must be exactly 8-bytes long.
Contents lxxxiii Start Close Intercept—Function 41 This function allows the application to intercept user requests to close the emulation program. Prerequisite Functions None. Function Call WinHLLAPI(STARTCLOSEINTERCEPT,lpbyString,lpwLength, lpwReturnnCode) WinHLLAPIAsync(hWnd,STARTCLOSEINTERCEPT,lpbyString, lpwLength,lpwReturnnCode) Call Parameters Return Parameters Parameter Description Data String A 5-byte string for returned semaphore address.
lxxxiv Contents Asynchronous Mode When asynchronous mode is enabled by calling WinHLLAPIAsync, the function initiates close intercept and immediately returns control to your Windows HLLAPI application. This frees your application to perform other tasks while waiting for close requests. Because asynchronous mode returns control immediately, you must use Windows version 3.x message notification to determine when close requests have occurred.
Contents lxxxv Start Host Notification—Function 23 This function enables notifying your Windows HLLAPI application of changes in the Host session presentation space or Operation Information Area (OIA). Prerequisite Functions None.
lxxxvi Remarks Contents Once enabled, Host notification is enabled until you call Stop Host Notification (function 25). Once you call this function, you can use Pause (function 18) to notify your Windows HLLAPI application when the presentation space and/or OIA of a Host session have been updated. Use Query Host Update (function 24) to determine which parts of the Host session (presentation space, OIA, or both) have been updated.
Contents lxxxvii Start Keystroke Intercept—Function 50 This function enables your Windows HLLAPI application to intercept keystrokes sent to a session by the user. Prerequisite Functions None.
lxxxviii Contents If position 2 of Data String is “D,” only AID keystrokes are intercepted. All other keystrokes are passed on to the appropriate Host session presentation space. Asynchronous Mode When asynchronous mode is enabled by calling WinHLLAPIAsync, the function initiates keystroke intercept and immediately returns control to your Windows HLLAPI application. This frees your application to perform other tasks while waiting for keystrokes.
Contents lxxxix Stop Close Intercept—Function 43 This function stops the application from intercepting close requests from the user. Subsequent close requests are processed normally by the emulator program. Prerequisite Functions Start Close Intercept (function 41). Function Call WinHLLAPI(STOPCLOSEINTERCEPT,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String One-character short name session ID of the presentation space. Data Length NA.
xc Contents Stop Host Notification—Function 25 This function disables notifying your Windows HLLAPI application of changes in the Host session presentation space or Operation Information Area (OIA). Prerequisite Functions Start Host Notification (function 23). Function Call WinHLLAPI(STOPHOSTNOTIFICATION,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String Short name session ID of the desired Host session, or space or null for the current Host session.
Contents xci Stop Keystroke Intercept—Function 53 This function disables the ability of your Windows HLLAPI application to intercept keystrokes. Prerequisite Functions Start Keystroke Intercept (function 50). Function Call WinHLLAPI(STOPKSINTERCEPT,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String One byte: short name session ID of the desired Host session, or space or null for the current Host session. Data Length NA (length of 1 is implied).
xcii Contents Wait—Function 4 This function determines whether the Host session is in a wait state. If, for some reason, the session is in a wait state, this function causes your Windows HLLAPI application to wait for the specified amount of time to see if the wait condition clears. The amount of time to wait is set by session options with Set Session Parameters (function 9). Prerequisite Functions Connect Presentation Space (function 1).
Contents xciii Although both APIs are supported, you should use WinHLLAPIAsync instead of WinHLLAPI whenever possible. Note that if NWAIT is specified, the WinHLLAPIAsync call will work the same as the WinHLLAPI call and not send a message.
xciv Contents Window Status—Function 104 This function allows the application to query or change a session’s window size, location, or visible state, or to query a session’s window handle or font characteristics. Prerequisite Functions Connect Window Services (function 101). Function Call WinHLLAPI(WINDOWSTATUS,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String See the following tables. Data Length NA (defaults to 16 or 20, depending on the status request).
Contents Data String xcv Description Set window status - a 16-byte string with the following format: u WHLL_WINDOWSTATUS_MAXIMIZE. Set the window to maximized (not valid with minimize, restore, size, or move). u WHLL_WINDOWSTATUS_RESTORE. Restore the window (not valid with maximize, minimize, size, or move). Bytes 5-6 Specifies the x-coordinate of the upper-left corner of the window. Bytes 7-8 Specifies the y-coordinate of the upper-left corner of the window.
xcvi Contents Data String Description Query extended window status - a 20-byte string with the following format: Byte 1 Short name session ID of the desired host session, or space or null for the current host session. Byte 2 WHLL_WINDOWSTATUS_EXTQUERY for query extended status. Bytes 3-4 An integer containing WHLL_WINDOWSTATUS_NULL. The following are possible return values. More than one status is possible. u WHLL_WINDOWSTATUS_SHOW. The window is visible. u WHLL_WINDOWSTATUS_HIDE.
Contents Return Codes Remarks xcvii Code Description WHLLOK The function was successful. WHLLNOTCONNECTED An invalid presentation space was specified, or was not connected for window services. WHLLPARAMETERERROR An invalid option was specified. WHLLSYSERROR The function failed due to a system error. WHLLPSENDED The session stopped. All coordinate positions, screen sizes, offsets, and font sizes are in pixels. This function is not supported for 5250 emulation.
xcviii Contents C H A P T E R 4 Extensions for the Windows Environment This chapter describes API extensions to Windows HLLAPI that allow asynchronous communication. These extensions have been designed for all implementations and versions of the Microsoft Windows graphical environment starting from Microsoft Windows version 3.0. They provide for Windows HLLAPI implementations and applications in 16- and 32-bit operating environments. Windows HLLAPI allows multithreaded Windows-based processes.
Contents xcix WinHLLAPIAsync( ) This function provides an asynchronous flavor to the following HLLAPI functions: STARTKSINTERCEPT, WAIT, STARTHOSTNOTIFICATION, STARTCLOSEINTERCEPT, SENDFILE, and RECEIVEFILE. You should use WinHLLAPIAsync( ) instead of the blocking versions of these functions.
c Contents WinHLLAPICleanup( ) This routine should be called by an application to deregister itself from a Windows HLLAPI implementation. Syntax BOOL WinHLLAPICleanup(void) Returns The return value indicates whether the deregistration was successful. It is non-zero if the application was successfully deregistered; otherwise it is zero. Windows HLLAPI Supplier Notes Use the WinHLLAPICleanup( ) call to indicate deregistration of a Windows HLLAPI application from a Windows HLLAPI implementation.
Contents ci WinHLLAPIIsBlocking( ) This function allows a task to determine if it is executing while waiting for a previous blocking call to complete. Syntax BOOL WinHLLAPIIsBlocking(void) Returns The return value specifies the outcome of the function. It is nonzero if there is an outstanding blocking call awaiting completion; otherwise it is zero.
cii Contents WinHLLAPICancelAsyncRequest( ) This function cancels an outstanding WinHLLAPIAsync( )-based request.
Contents ciii WinHLLAPICancelBlockingCall( ) This function cancels any outstanding blocking operation for its thread. Any outstanding blocked call canceled will cause an error code of WHLLCANCEL to be generated. Examples of blocking calls are WinHLLAPI with function number set to GETKEY, WAIT, PAUSE, SENDFILE or RECEIVEFILE. You should use WinHLLAPIAsync( ) instead of the blocking versions of these functions.
civ Contents WinHLLAPIStartup( ) This function allows an application to specify the version of Windows HLLAPI required and to retrieve details of the specific Windows HLLAPI implementation. This function MUST be called by an application before issuing any further Windows HLLAPI calls to register itself with a Windows HLLAPI implementation.
Contents App versions DLL Versions To WinHLLAPI Startup From WinHLLAPI Startup Result 1.0 1.0 1.0 1.0 use 1.0 1.0 2.0 1.0 2.0 1.0 use 1.0 1.0 1.0 2.0 1.0 2.0 use 1.0 1.0 2.0 3.0 1.0 WHLLINVALID fail 2.0 3.0 1.0 3.0 1.0 app fails 1.0 2.0 3.0 1.0 2.0 3.0 3.0 3.0 use 3.0 cv Having made its last Windows HLLAPI call, an application should call the WinHLLAPICleanup( ) routine.
cvi Contents WinHLLAPISetBlockingHook( ) This function installs a new function which a Windows HLLAPI Implementation should use to implement blocking HLLAPI function calls. This mechanism is provided to allow a Windows version 3.x application to make blocking calls without blocking the rest of the system. By default under Windows NT, blocking calls will suspend the calling application’s thread until the request completes. Therefore if a single-threaded application is targeted at both Windows version 3.
Contents WinHLLAPIUnhookBlockingHook( ) This function removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism. Syntax BOOL WinHLLAPIUnhookBlockingHook(void) Returns The return value specifies the outcome of the function. It is nonzero if the default mechanism is successfully reinstalled; otherwise it is zero.
cviii Contents A P P E N D I X A WHLLAPI.H - Definitions / Declarations for the Windows HLLAPI Specification /****************************************************************************\ * * * whllapi.h Windows HLLAPI functions, types, and definitions * * * * Version 1.
Contents #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define FINDFIELDLENGTH COPYSTRINGTOFIELD COPYFIELDTOSTRING SETCURSOR STARTCLOSEINTERCEPT QUERYCLOSEINTERCEPT STOPCLOSEINTERCEPT STARTKSINTERCEPT GETKEY POSTINTERCEPTSTATUS STOPKSINTERCEPT LOCKPSAPI LOCKWSAPI SENDFILE RECEIVEFILE CONVERT CONNECTWINDOWSERVICES DISCONNECTWINDOWSE
cx Contents /****** Convert Row or Column values ****************************************/ #define WHLL_CONVERT_POSITION 'P' #define WHLL_CONVERT_ROW 'R' /******* Storage Manager Sub-Function values ********************************/ #define #define #define #define WHLL_GETSTORAGE WHLL_FREESTORAGE WHLL_FREEALLSTORAGE WHLL_QUERYFREESTORAGE 1 2 3 4 /****** Change PS Name values ***********************************************/ #define WHLL_CHANGEPSNAME_SET #define WHLL_CHANGEPSNAME_RESET 0x01 0x02 /*****
Contents /****** Windows HLLAPI Return Codes *****************************************/ #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define WHLLOK WHLLNOTCONNECTED WHLLBLOCKNOTAVAIL WHLLPARAMETERERROR WHLLBLOCKIDINVALID WHLLFTXCOMPLETE WHLLFTXSEGMENTED WHLLPSBUSY WHL
cxii Contents /****** Windows HLLAPI Extentions Return Codes ******************************/ #define #define #define #define #define WHLLALREADY WHLLINVALID WHLLCANCEL WHLLSYSNOTREADY WHLLVERNOTSUPPORTED 0xF000 0xF001 0xF002 0xF003 0xF004 /* /* /* /* /* An async call is already outstanding */ Async Task Id is invalid */ Blocking call was cancelled */ Underlying subsystem not started */ Application version not supported */ /****** Windows HLLAPI structure ********************************************/
Contents A P P E N D I X B Attributes This appendix contains the following tables: • 3270 and 5250 Character Attributes. • 3270 and 5250 Character Color Attributes. • 3270 and 5250 Field Attributes. Note The attribute bit positions are in IBM format. The leftmost bit in the byte is 0.
cxiv Contents Character Attributes 3270 character attributes Bit Position 0-1 Meaning Character highlighting 00 = Normal 01 = Blink 10 = Reverse video 11 = Underline 2-4 Character color (color remap may override this definition) 000 = Default 100 = Green 001 = Blue 101 = Turquoise 010 = Red 110 = Yellow 011 = Pink 111 = White 5-7 Reserved (not used) 5250 Character Attributes Bit Position Meaning 0 Reverse image 0 = Normal 1 Underscore 0 = None 1 = Underscore 2 Blink 0 = None 1 = Blink 3
Contents Character Color Attributes Bit Position 0-3 Meaning Background character colors 0000 = Black 0001 = Blue 0010 = Green 0011 = Cyan 4-7 0100 = Red 0101 = Magenta 0110 = Brown 0111 = White Foreground character colors 0000 = Black 0001 = Blue 0010 = Green 0011 = Cyan 0100 = Red 0101 = Magenta 0110 = Brown 0111 = White 1000 = Gray 1001 = Light blue 1010 = Light green 1011 = Light cyan 1100 = Light red 1101 = Light magenta 1110 = Yellow 1111 = High intensity white cxv
cxvi Contents Field Attributes 3270 field attributes Bit Position 0-1 2 Meaning Both set to 1 (field attribute byte) Unprotected/protected 0 = Unprotected data field 1 = Protected data field 3 Alpha/numeric 0 = Alphanumeric data 1 = Numeric data only 4-5 I/SPD 00 = Normal intensity, pen not detectable 01 = Normal intensity, pen detectable 10 = High intensity, pen detectable 11 = Non-display, pen not detectable 6 Reserved 7 MDT (Modified Data Tag) 0 = Field has not been modified 1 = Field has been
Contents 5250 field attributes Bit Position 0 Meaning Field attribute flag 0=Not a field attribute 1=Field attribute byte 1 Visibility 0 = Non-display 1 = Display 2 Unprotected/protected 0 = Unprotected data field 1 = Protected data field 3 Intensity 0 = Normal 1 = High 4-6 Field Type 000 =Alphanumeric: all characters allowed 001 = Alphabetic only 010 = Numeric shift: automatic shift for numerics 011 = Numeric only 100=Reserved 101=Digits: 110=Magnetic stripe reader data only 111=Signed Numeric 7
cxviii Contents A P P E N D I X C Extended Windows HLLAPI Functions This appendix lists the WinHLLAPI functions defined in release 1.0 of IBM Extended Services for OS/2 EHLLAPI Programming Reference but not required for WinHLLAPI compliance.
Contents cxix Allocate Communications Buffer—Function 123 This function allows the application to obtain exclusive control of a memory buffer to be used for read and write structured field requests. A buffer address must be passed on to the functions that read and write the structured field requests. Prerequisite Functions None.
cxx Contents When this limit is reached, additional requests to WinHLLAPI will return an 11, indicating that the resource is unavailable.
Contents cxxi Connect Structured Fields—Function 120 This function allows an application to establish a connection with a Host session. Prerequisite Functions None Function Call WinHLLAPI(CONNECTSTRFLDS,lpbyString,lpwLength, lpwReturnnCode) Call Parameters Parameter Description Data String An 11-byte string for returned semaphore address. The first byte is a short name session ID of the session to query, or space or null for the current session.
cxxii Contents Return Codes Remarks Code Description WHLLOK The function was successful. WHLLNOTCONNECTED An invalid presentation space was specified. WHLLPARAMETERERROR An invalid option was specified. WHLLSYSERROR The function failed due to a system error. WHLLNOTSUPPORTED The function is not supported by the emulation program. WHLLSFACONN The function failed because another application is already connected to this session.
Contents cxxiii The semaphore is set during the connect process because the emulator is in an inbound disabled state. The semaphore is cleared for the first time when outbound data destined for the connecting DOID is received by the emulator. Because the emulator is in an inbound disabled state, a host application cannot be started via a Write Structured Fields (127) function call. The host application must be started manually, or by issuing a Send Key (3).
cxxiv Contents Disconnect Structured Fields—Function 121 This function drops the connection between the Windows HLLAPI application and the specified session. Prerequisite Functions Connect Structured Fields (function 120). Function Call WinHLLAPI(DISCONSTRFLDS,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String A 3-byte string with the following format: Return Codes Remarks Byte 1 Short name session ID.
Contents cxxv Free Communications Buffer—Function 124 This function allows the application to release exclusive control of a buffer that is no longer required by the application. Prerequisite Functions Allocate Communications Buffer (123). Function Call WinHLLAPI(FREECOMMBUFF,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String A 6-byte string with the following format: Return Code Remarks Byte 1-2 16-bit length of the buffer to be freed.
cxxvi Contents Get Request Completion—Function 125 This function allows the application to determine the status of a previous asynchronous function request issued to WinHLLAPI, and obtains the function parameter list before using the data string again. Prerequisite Functions Connect Structured Fields (120) and either Read Structured Fields (126) or Write Structured Fields (127).
Contents Return Codes Code Description WHLLOK The function was successful. WHLLNOTCONNECTED An invalid presentation space was specified. WHLLPARAMETERERROR An invalid option was specified. WHLLSYSERROR The function failed due to a system error. WHLLNOTCOMPLETE The requested function was not completed. WHLLNOMATCH A matching request was not found.
cxxviii Contents The user specifies whether the application can query of wait for one of the following: u A specific asynchronous function request by supplying the Request ID of that function and a non-blank session short name. u The first completed asynchronous function request by supplying a Request ID of 0x0000 and a blank session short name. u The first completed asynchronous function request for a specified session by supplying a Request ID of 0x0000 and a non-blank session short name.
Contents cxxix If a nonzero Request ID is supplied, this function checks for the completion of only the function associated with the ID. If the return code is zero, the application should check the returned data string for information pertaining to the completion of the requested asynchronous function. Note The communications subsystem allows for a maximum of 20 asynchronous requests per application to be outstanding.
cxxx Contents Lock Presentation Space API—Function 60 This function allows the application to obtain or release exclusive control of the presentation space. Prerequisite Functions Connect Presentation Space (function 1). Function Call WinHLLAPI(LOCKPSAPI,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String Locking parameters - a 3-byte string with the following format: Byte 1 Short name session ID, or space or null for the current session.
Contents cxxxi Lock Window Services API—Function 61 This function allows the application to obtain or release exclusive control of the presentation space window services. Prerequisite Functions Connect Window Services (function 101). Function Call WinHLLAPI(LOCKWSAPI,lpbyString,lpwLength,lpwReturnnCode) Call Parameters Parameter Description Data String Locking parameters - a 3-byte string with the following format: Byte 1 Short name session ID, or space or null for the current session.
cxxxii Contents Query Communication Buffer Size—Function 122 This function allows the application to determine the maximum and optimum inbound and outbound buffer size supported by the communications engine. These buffer sizes are to be used with the Allocate Communications Buffer (123) function to optimize the performance of the structured field functions. Prerequisite Functions None.
Contents cxxxiii byte. For destination/origin connections, the 8-byte header supplied in the Read or Write structured fields data buffer is stripped and 9 bytes are then prefixed to the data. The application should compare the size of the actual data in the data buffer (not including the 8-byte header) to the buffer size returned from the Query Communications Buffer Size (122) function minus 9 bytes.
cxxxiv Contents Read Structured Fields—Function 126 This function receives structured field data from the host application. If the call specifies asynchronous (A), the application receives control immediately after the call, even if host data is not available. If the call specifies synchronous (S), WinHLLAPI waits for host data to become available before returning control to the application. The application provides the buffer address in which data from the host is to be placed.
Contents Return Parameters cxxxv Parameter Description Data String When the A (asynchronous) control option is specified and the request is successfully completed, the following are returned: Bytes 9-10 A 16-bit value representing the destination/origin ID returned to the application by the emulator. This function request ID is used by the Get Request Completion (125) function to determine the status of this function call.
cxxxvi Contents The application must correct the situation if one of the following return codes is specified: WHLLTRANCANCL Is returned if the first Read Structured Fields (126) or Write Structured Fields (127) is requested after an outbound transmission from the host is canceled. Remarks WHLLHOSTCLOST Which requires the application to disconnect from the communications subsystem and reconnect to establish communications with the host again.
Contents cxxxvii Bytes 8-m are where the structured field messages are returned. The following occurs when the call is returned: u The word at position 2 contains the length (8-m) of the structured field messages. u The word at position 8 contains the length of the first structured field message. Bytes 10-m contain the actual data of the structured field message.
cxxxviii Contents The following steps must be completed to determine the outcome of an asynchronous Read Structured Fields (126) function call: u If the WinHLLAPI return code is not zero, the request failed. No asynchronous request has been made. The application must take appropriate actions before attempting the call again. u If the return code is zero, the application should wait until the semaphore is cleared by using the Get Request Completion (125) function.
Contents cxxxix Storage Manager—Function 17 This function allows your application elementary control of blocks of memory for use with the Windows HLLAPI function calls. The Storage Manager (17) function allows easy migration of existing applications (typically BASIC interpreter applications) that use Storage Manager (17) functions. The new BASIC applications can use this function, but are not required to. The other supported languages may also use this function.
cxl Contents WHLLBLOCKNOTAVAIL You requested more storage than is available. WHLLSYSERROR The function failed due to a system error. Any time results are unpredictable. WHLLNOTSUPPORTED The function was not supported by the emulation program. Free Storage The Free Storage sub-function frees the block of storage allocated by the Get Storage sub-function.
Contents Call Parameters Return Parameters Return Codes cxli Parameter Description Data String NA Data Length NA PS Position 03 (QUERYFREESTORAGE) Parameter Description Data Length Size of the largest block available. (0xFFFF indicates a full 64 Kbytes) Code Description WHLLOK The Query was successful. WHLLSYSERROR The function failed due to a system error. Any time results are unpredictable. WHLLNOTSUPPORTED The function was not supported by the emulation program.
cxlii Contents Write Structured Fields—Function 127 This function writes structured field data from the Windows HLLAPI application to the host application. If the call specifies asynchronous (A), the application receives control as soon as the request has been successfully queued to the subsystem.
Contents cxliii Bytes 9-10 A 16-bit value representing the destination/origin ID returned to the application by the emulator. This function request ID is used by the Get Request Completion (125) function to determine the status of this function call. Bytes 11-14 A 4-byte value in which the semaphore address is returned by WINHLLAPI. The application may wait upon this semaphore. When the semaphore is cleared, the application must issue the Get Request Completion (125) function call.
cxliv Contents The application must correct the situation if one of the following return codes is specified: Remarks Code Description WHLLTRANCANCL Is returned if the first Read Structured Fields (126) or Write Structured Fields (127) is requested after an outbound transmission from the host is canceled. WHLLHOSTCLOST Which requires the application to disconnect from the communications subsystem and reconnect to establish communications with the host again.
Contents cxlv Bytes 8-m are where the structured field messages are returned. The following occurs when the call is returned: u The word at position 2 contains the length (8-m) of the structured field messages. u The word at position 8 contains the length of the first structured field message. u Bytes 10-m contain the actual data of the structured field message.
cxlvi Contents The following steps must be completed to determine the outcome of an asynchronous Write Structured Fields (127) function call: u If the WinHLLAPI return code is not zero, the request failed. No asynchronous request has been made. The application must take appropriate actions before attempting the call again. u If the return code is zero, the application should wait until the semaphore is cleared by using the Get Request Completion (125) function.
Contents A P P E N D I X cxlvii D Query Reply Data Structures for Windows HLLAPI This appendix lists and defines the query reply structures supported by the Windows HLLAPI structured field interface. See the IBM 3270 Information Display System Data Stream Programmer’s Guide for additional information on Query Reply Data Structures. 1.
cxlviii Contents The DDM Query Reply Several DDM query reply formats will be supported. Some of these formats are listed below: Table D-l.
Contents cxlix VERS: The value given in VERS is used to indicate the version of PCLK installed in the terminal at the time the query reply is returned. For example, 0x0001 indicates PCLK version 1.1. See the IBM 3270 Information Display System Data Stream Programmer’s Reference for the field definitions for this query reply. Base DDM Query Reply Formats The following query reply formats are examples of some of the Base + SDP combinations possible. Not all of the combinations are shown. Table D-4.
cl Contents Table D-4. Base DDM Query Reply Format with Name and Direct Access SDPs (continued) Offset Length Content Meaning 14 -(13+n) n bytes Name Name of the Remote Application Program 14 + n 1 byte 0x04 Parameter Length 15 + n 1 byte 0x01 Direct Access ID 16+n - 17+n n-2 bytes VERS Destination/Origin ID assigned by the subsystem The SDPs begin at offsets 12 and (14 + n) where “n” is the length of the application name supplied at offset 14.
Contents cli The SDPs begin at offsets 12 and 16. See the IBM 3270 Information Display System Data Stream Programmer’s Reference for the field definitions for this query reply. The IBM Auxiliary Device Query Reply The Auxiliary Device Query Reply is used to indicate to the host application the support of an IBM auxiliary device, which uses a data stream defined by IBM. See the IBM 3270 Data Stream Programmer’s Reference Manual for more information.
clii Contents 1 byte 0x01 Direct Access 1 word DOID Destination/Origin ID assigned by the subsystem 13-14 QUERY This bit must be set to Binary 1 for all IBM auxiliary devices to indicate that it supports receiving a Read Partition (Query, Query List). The host application may then use a Read Partition directed to the auxiliary device to determine its characteristics. The destination/origin structured field is used to direct the Read Partition structured field to the auxiliary device.
Contents cliii Direct Access Self-Defining Parameter This self-defining parameter provides the ID for use in the destination/origin structured field in the direct access of the IBM auxiliary device. This SDP is always required to accompany the base query reply. Table D-7.
cliv Contents The OEM Auxiliary Device Query Reply The OEM Auxiliary Device Query Reply format is as follows: Table D-9.
Contents 2-3 2 bytes VERS Protocol Version VERS: The value given in VERS is used to indicate the version of PCLK installed in the terminal at the time the query reply is returned. For example, 0x000l indicates PCLK version 1.1.
clvi Contents The Cooperative Processing Requester Query Reply The Cooperative Processing Requester query reply is also called the SRPI query reply or the CPSI query reply. The format is as follows: Table D-12.
Contents clvii The Product Defined Query Reply This query reply is used by IBM products using registered subidentifiers within the X ' 9C ' data structure. The Product Defined Data Stream query reply indicates support of a 3270DS workstation auxiliary device which uses an IBM product defined data stream. The data stream is not defined by a format architecture document having an identifiable control point such as an architecture review board.
clviii Contents Valid values for REFID (offset 6) and SSID (offset 7) of the Product Defined query reply are as follows: Table D-14. IBM Product Defined Query Reply Base Format REFID SSID 0x01 Product and Data Stream Documentation 5080 Graphics System: This reference ID indicates the 5080 Graphics System data stream is supported by the auxiliary device.
Contents clix Table D-15. IBM Product Defined Direct Access SDP Offset Length Content Meaning 0 1 byte 0x04 Parameter Length 1 1 byte 0x03 PCLK Protocol Controls 2-3 2 bytes DOID Destination/Origin ID DOID: The value in these bytes is used in the ID field of the destination/origin structured field to identify the auxiliary device as the destination or origin of the data which follows.
clx Contents Direct Access Self-Defining Parameter The presence of the Direct Access ID self defining parameter indicates the auxiliary device may be accessed directly by using the destination/origin structured field. Table D-17.
