EHLLAPI Functions

This chapter describes each individual Personal Communications EHLLAPI function in detail and explains how to use the EHLLAPI program sampler. The functions are arranged alphabetically by name. The functions are explained for both the standard and enhanced interfaces.

Unicode Support for Code Pages 1390/1399 and 1137

The following EHLLAPI functions are enabled for Japanese code page 1390/1399 and Hindi code page 1137 support on a Unicode session:

• Convert Position or Convert RowCol (1137 only)
• Copy Field to String
• Copy Presentation Space
• Copy Presentation Space to String
• Copy String to Field
• Copy String to Presentation Space
• Get Key
• Search Field
• Search Presentation Space
• Send Key
• Set Cursor (1137 only)
• Set Session Parameters

See the specific section for each function for details on Japanese code page 1390/1399 and Hindi code page 1137.

Page Layout Conventions

All EHLLAPI function calls are presented in the same format so that you can quickly retrieve the information you need. The format is:

• Function Name (Function Number)
  • Prerequisite Calls
  • Call Parameters
  • Return Parameters
  • Notes on Using This Function

Prerequisite Calls

"Prerequisite Calls" lists any calls that must be made prior to calling the function being discussed.

Call Parameters

"Call Parameters" lists the parameters that must be defined in your program to call the discussed EHLLAPI function and explains how those parameters are to be defined. If a parameter is never used by a function, then NA (not applicable) is listed. If a parameter can be overridden by certain values of session parameters defined with calls to the Set Session Parameters (9) function, such session parameters are named.

Return Parameters

"Return Parameters" lists the parameters that must be received by your program after a call to the discussed EHLLAPI function and explains how to interpret those parameters.

Notes on Using This Function

"Notes on Using This Function" lists any session options that affect the function under discussion. It also provides technical information about using the function and application development tips.

Summary of EHLLAPI Functions

Table 6 is the summary of the EHLLAPI functions:

Allocate Communications Buffer (123)

The Allocate Communications Buffer function obtains a buffer from the operating system. A buffer address must be passed on both the Read Structured Fields (126) and Write Structured Fields (127) functions.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

The calling data string can contain:

Return Parameters

Notes on Using This Function

1. The EHLLAPI obtains a buffer from the operating system memory management and places the buffer address into the return parameter string. The requested buffer size (length) is also passed in the parameter string. The buffer size can be from 1 byte to 64 KB minus 256 bytes (X'FF00' bytes) in length.

   See "Query Communications Buffer Size (122)" for information regarding buffer size.

2. Buffers obtained using this function must not be shared among different processes. If this is attempted, the applications will experience unpredictable results.
3. An EHLLAPI application must issue a Free Communications Buffer (124) function to free the allocated memory.
4. A maximum of 10 buffers can be allocated to an application. If this limit is reached, a return code for resource unavailable (RC=11) will be returned.
5. The Reset System (21) function frees buffers allocated by this function.

Cancel File Transfer (92)

The Cancel File Transfer function causes any current EHLLAPI initiated Send File or Receive File for the specified session to immediately return.

Prerequisite Calls

Send File (90) or Receive File (91)

Call Parameters

The calling data structure contains these elements

Return Parameters

Notes on Using This Function

Since both Send File (90) and Receive File (91) are blocking calls, this function must always be issued on a different thread.

Change PS Window Name (106)

The Change PS Window Name 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 Calls

Connect Window Services (101)

Call Parameters

The calling data string can contain:

Return Parameters

Notes on Using This Function

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.

If the application fails to reset the presentation space name before exiting, the exit list processing resets the name.

Change Switch List LT Name (105)

The Change Switch List LT Name function allows the application to change or reset a switch list for a selected logical terminal (LT). The application must specify on the call the name to be inserted in the switch list.

Prerequisite Calls

Connect Window Services (101)

Call Parameters

The calling data string can contain:

Return Parameters

Notes on Using This Function

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.

If the application fails to reset the switch list LT name before exiting, the exit list processing resets the name.

Connect for Structured Fields (120)

The Connect for Structured Fields function allows an application to establish a connection to the emulation program to exchange structured field data with a host application. The workstation application must provide the Query Reply data field and must point to it with in the parameter string. The destination/origin ID returned by the emulator will be returned to the application.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

The calling data string can contain:

Return Parameters

Notes on Using This Function

1. EHLLAPI scans the query reply buffers for the destination/origin ID (DOID) self-defining parameter (SDP) to determine the contents of the DOID field of the query reply. If this value is X'0000', the emulator will assign a DOID to the application and EHLLAPI will fill in the DOID field of the query reply with the assigned ID. If the value specified by the application in the DOID field of the query reply is a nonzero value, the emulator will assign the specified value as the application’s DOID, assuming that the ID has not been previously assigned. If the specified DOID is already in use, a return code of 2 will be returned by EHLLAPI.
2. The application should build the Query Reply Data structures in the application’s private memory. Refer to Appendix A. Query Reply Data Structures Supported by EHLLAPI, for the detailed formats and usages of the query reply data structures supported by EHLLAPI.
3. Only cursory checking is performed on the Query Reply Data. Only the ID and the length of the structure are checked for validity.
4. Only one DDM base type connect is allowed per host session. If the DDM connection supports the self-defining parameter (SDP) for the destination origin ID (DOID), then multiple connects are allowed.
5. If return code RC=32 or RC=39 is received, an application is already connected to the selected session and use of that presentation space should be approached with caution. Conflicts with SRPI, file transfer, and other EHLLAPI applications might result.

Connect Presentation Space (1)

The Connect Presentation Space function establishes a connection between your EHLLAPI application program and the host presentation space.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

The calling data string can contain:

Return Parameters

The Connect Presentation Space function sets the return code to indicate the status of the attempt and, if successful, the status of the host presentation space.

Notes on Using This Function

1. The Connect Presentation Space function is affected by the CONLOG/CONPHYS session option.
2. An EHLLAPI application cannot be connected to multiple presentation spaces concurrently. Calls requiring the Connect Presentation Space function as a prerequisite use the currently connected presentation space. For example, if an application is connected to presentation space A, B, and C in that order, the application must connect to B or A again to issue functions.
3. Each thread that requests a Connect Presentation Space must have a corresponding Disconnect Presentation Space (2), or one of the threads must issue a Reset System (21), which affects all threads and disconnects any remaining connections.
4. More than one EHLLAPI application can share a presentation space, if the applications support sharing (that is, if they were developed to work together and if they exhibit predictable behavior) and have compatible read/write access and keyword options as set in the Set Sessions Parameters (9) function. For more information, see Set Session Parameters (9).
5. Because the Connect Presentation Space and Start Keystroke Intercept (50) functions share common subsystem functions, successful requests by an application to share either of these functions for the same session can affect the request of these two functions by other applications. For example, if application A successfully requests a Connect Presentation Space for a session with Write_Read access and KEY$abcdefgh as the keyword, a request by application B to Connect Presentation Space for a session and Start Keystroke Intercept is successful only if both applications have set compatible read/write options.
6. You cannot connect to a session that is defined as a logical printer session. Refer to Administrator's Guide and Reference for more information.

Connect Window Services (101)

The Connect Window Services function allows the application to manage the presentation space windows. Only one EHLLAPI application at a time can be connected to a presentation space for window services.

An EHLLAPI application can connect to more than one presentation space concurrently for window services.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

The calling data string can contain:

Return Parameters

Notes on Using This Function

1. An EHLLAPI application can be connected to multiple presentation space windows at the same time. The application can go back and forth between the connected presentation space windows without having to disconnect. For example, if an application is connected to presentation space windows A, B, and C, the application can access all of A, B, and C at the same time, and the other applications cannot access A, B, or C.
2. A Connect Window Services function is sufficient for the process. However, each thread that requests a Connect Window Services must have a corresponding Disconnect Window Services (102), or one of the threads must issue a Reset System (21), which affects all threads and disconnects any remaining connections.

Convert Position or Convert RowCol (99)

The Convert Position or Convert RowCol function converts the host presentation space positional value into the display row and column coordinates or converts the display row and column coordinates into the host presentation space positional value. This function does not change the cursor position.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

The calling data string can contain:

Return Parameters

This function returns a length and a return code.

Length:

For the Convert Position function (P as the second character in the calling data string), a number between 1 and 43 (for PC/3270) or 27 (for PC400) is returned. This value is the number of the row that contains the PS position contained in the calling PS position parameter. The upper limit can be smaller than 43 (for PC/3270) or 27 (for PC400) depending on how the host presentation space is configured.

For the Convert RowCol function (R as the second character in the calling data string), a value of 0 indicates an error in the input value for row (calling length parameter).

Return Code:

The Convert Position or RowCol function is the exception to the rule that the fourth return parameter always contains a return code. For this function, the value returned in the fourth parameter is called a status code. This status code can contain data or a return code. Your application must provide for processing of this status code to prevent unpredictable results or an error.

• If the value of the fourth parameter is 0, 9998, or 9999, it is a return code.
• For the Convert Position function (P as the second character of the calling data string), a value in the range of 1-132 is the number of the column that contains the PS position passed in the calling PS Position parameter. The upper limit can be smaller than 132 depending on how the host presentation space is configured.
• For the Convert RowCol function (R as the second character of the calling data string), a value in the range of 1-3564 represents the host presentation space position that corresponds to the row and column values passed in the calling length and PS position parameters, respectively. The upper limit can be smaller than 3564 depending on how the host presentation space is configured.

The following status codes are defined:

Notes on Using This Function

1. To configure your presentation space, refer to Administrator's Guide and Reference
2. To find out how many rows and columns are in your presentation space, examine the returned data string parameter for the Query Session Status (22) function. See Query Session Status (22).

1137 Code Page Support

Unicode functionality is supported only on 5250 sessions.

Convert Position or Convert RowCol is Hindi enabled in order to return the beginning of the cluster. The usage of Convert Position or Convert RowCol is the same as the SBCS session.

Copy Field to String (34)

The Copy Field to String function transfers characters from a field in the host-connected presentation space into a string.

The Copy Field to String function translates the characters in the host source presentation space into American National Standard Code for Information Interchange (ASCII). Attribute bytes and other characters not represented in ASCII normally are translated into blanks.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a data string, length, and a return code.

Data String:

A string containing data from the identified field in the host presentation space. The first byte in the returned data string is the beginning byte of the identified field in the host presentation space. The number of bytes in the returned data string is determined by the smaller of:

• Number of bytes specified in the calling length parameter
• Number of bytes in the identified field in the host presentation space

Length:

The length of the data returned.

Return Code:

The following codes are defined:

Notes on Using This Function

1. The field position and length information can be found by using the Find Field Position (31) and Find Field Length (32) functions. The Copy Field to String function can be used with either protected or unprotected fields, but only in a field-formatted host presentation space.
2. The copy is ended when one of the following conditions is encountered:
   • When the end of the field is reached
   • When the length of the target string is exceeded
3. DBCS Only: If the target string is ended at the higher byte of the DBCS character, the byte is translated into a blank. If the EAD option is set to on, three bytes are returned for each character. If both the EAB and EAD options are set to on, four bytes are returned for each character.
   Note:

   When the field wraps at the end of the presentation space, wrapping occurs when the end of the presentation space is reached.
4. DBCS Only: The Set Session Parameters (9) function EAD option is used with this function to return a 2-byte EAD. If the EAD option is specified instead of the EAB option, EAD is returned preceding each character. If both the EAB and EAD options are specified, EAD is returned preceding the EAB.
5. An EAB can be returned when the Set Session Parameters (9) function EAB option is used. EAB is related to each character in the presentation space and is returned preceding each character.
6. The Copy Field to String function is affected by the ATTRB/NOATTRB/NULLATTRB, the EAB/NOEAB, the XLATE/NOXLATE, the DISPLAY/NODISPLAY, the DISPLAY/NODISPLAY, the EAD/NOEAD (for DBCS only), and the NOSO/SPACESO/SO (for DBCS only) session options. Refer to items 5; 13 and 14; 17; and 20 and 21 for more information.

   As previously stated, the return of attributes by the various Copy (5, 8, and 34) functions is affected by the Set Session Parameters (9) function. The involved set session parameters have the following effect:

   Set Session Parameter

   Effect on the COPY Function

   NOEAB and NOEAD

   Attributes are not returned. Only text is copied from the presentation space to the user buffer.

   EAB and NOXLATE

   Attributes are returned as defined in the following tables.

   EAB and XLATE

   The colors used for the presentation space display are returned. Colors can be remapped; so the attribute colors are not the ones returned by the COPY functions when XLATE and EAB are on at the same time.

   EAD

   Double-byte character set attributes are returned as shown in the following tables.

   The returned character attributes are defined in the following tables. The attribute bit positions are in IBM format with bit 0 the left most bit in the byte.

   3270 character attributes are returned from the host to the emulator. The following table applies when EAB and NOXLATE are set.

   Bit Position	Meaning
   0-1	Character highlighting 00 = Normal 01 = Blink 10 = Reverse video 11 = Underline
   2-4	Character color (Color remap can override this color definition.) 000 = Default 001 = Blue 010 = Red 011 = Pink 100 = Green 101 = Turquoise 110 = Yellow 111 = White
   5-6	Character attributes 00 = Default value 11 = Double byte character
   7	Reserved

   5250 character attributes are returned from the host to the emulator. The following table applies when EAB and NOXLATE are set.

   Bit Position	Meaning
   0	Reverse image 0 = Normal image 1 = Reverse image
   1	Underline 0 = No underline 1 = Underline
   2	Blink 0 = Not blink 1 = Blink
   3	Separator of columns 0 = No separator 1 = Separator
   4-7	Reserved

   The following table shows Personal Communications character color attributes. The following table applies when EAB and XLATE are set.

   Bit Position	Meaning
   0-3	Background character colors 0000 = Black 0001 = Blue 0010 = Green 0011 = Cyan 0100 = Red 0101 = Magenta 0110 = Brown (3270), Yellow (5250) 0111 = White
   4-7	Foreground character colors 0000 = Black 0001 = Blue 0010 = Green 0011 = Cyan 0100 = Red 0101 = Magenta 0110 = Brown (3270), Yellow (5250) 0111 = White 1000 = Gray 1001 = Light blue 1010 = Light green 1011 = Light cyan 1100 = Light red 1101 = Light magenta 1110 = Yellow 1111 = White (high intensity)

   • Double-byte character set attributes (for DBCS only)
     • The first byte

       Bit Position	Character Position	Field Attribute Position
       0	Double-byte character	Reserved
       1	The first byte of the double-byte character	Reserved
       2	SO	Reserved
       3-4	SI (Bit position 3)	5250 DBCS related field When the value of bit position 7 is 0: 00 = Default 01 = DBCS only 10 = Either DBCS or SBCS 11 = Mixture of DBCS and SBCS When the value of bit position 7 is 1: 00 = Reserved 01 = DBCS only without SO/SI 10 = Reserved 11 = Reserved
       5	Reserved	SO/SI enable (3270 only)
       6	Reserved	Character attributes exist (3270 only)
       7	Reserved	5250 DBCS related extended field 0 = Basic double-byte field 1 = Extended double-byte field

     • The second byte

       Bit Position	Character Position	Field Attribute Position
       0	Reserved	Left grid line (3270 only)
       1	Reserved	Upper grid line (3270 only)
       2	Reserved	Right grid line (3270 only)
       3	Reserved	Under grid line (3270 only)
       4	Left grid line	Left grid line
       5	Upper grid line	Upper grid line
       6-7	Reserved	Reserved

   For a PS/2 monochrome display, the characters in the application (workstation) session appear as various shades of gray. This is required to give users their remapped colors in the EHLLAPI application session so they can get what they see in their host application presentation spaces.

7. To use this function, preallocate memory to receive the returned data string parameter. The statements required to preallocate this memory vary depending on the language in which your application is written. Refer to Memory Allocation for more information.

1390/1399 Code Page Support

Unicode functionality is supported only on 3270 and 5250 sessions.

In a Unicode session, the characters in the host source presentation space are translated into Unicode. Attribute bytes are normally translated into blanks.

The XLATE option (that can be specified using the Set Session Parameters function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a data string, length, and a return code.

Data String:

String containing the Unicode data is returned.

Length:

Number of Unicode characters copied into string.

Return Code:

The following codes are defined:

Notes on Using This Function

The following options are supported in a Unicode session for Copy Field To String (34) and function in the same way as in DBCS:

• NOATTRB
• ATTRB
• NULLATTRB
• EAB
• NOEAB
• NOXLATE
• DISPLAY
• NODISPLAY

1137 Code Page Support

Unicode functionality is supported only on 5250 sessions.

In a Unicode session, the characters in the host source presentation space are translated into Unicode. Attribute bytes are normally translated into blanks.

The XLATE option (that can be specified using the Set Session Parameters function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a data string, length, and a return code.

Data String:

String containing the Unicode data is returned.

Length:

Number of Unicode characters copied into string. To get the number of bytes, multiply by 2.

Return Code:

The following codes are defined:

Notes on Using This Function

The following options are supported in a Unicode session for Copy Field To String and function in the same way as in SBCS:

• NOATTRB
• ATTRB
• NULLATTRB
• EAB
• NOEAB
• NOXLATE
• DISPLAY
• NODISPLAY

Copy OIA (13)

The Copy OIA function returns the current operator information area (OIA) data from the host-connected presentation space.

The OIA is located under the bottom dividing line of the screen and is used to display session status information about the connection between the workstation and the host.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a data string and a return code.

Data String:

A 103-byte string for 16-bit and 104-byte string for 32-bit. See Format of the Returned OIA Data String for more information.

Return Code:

The following codes are defined:

Notes on Using This Function

1. The OIA Group consists of the bits that show the status of the connected sessions. The group is categorized by the represented host function. (For example, Group 8 consists of the bits that show all conditions of the input inhibit in the session.) The states of each group are ordered so that the high-order bits represent the indicators of higher priority. That is, bit 7 has priority over bit 0. Therefore, if more than one state is active within a group, the state with the highest priority is the active state within that group.
2. To use this function, preallocate memory to receive the returned data string parameter. The statements required to preallocate this memory vary depending on the language in which your application is written. Refer to Memory Allocation for more information.

Format of the Returned OIA Data String

The OIA data string contains the following information:

PC/3270 OIA Group Indicator Meanings and Its Image

The OIA image group consists of an 80-byte ASCII character string with no attribute bytes that contains the OIA image in host code points. Figure 2 shows the hexadecimal codes found in the host presentation space, and the characters they represent. The returned data can be translated into OIA graphics characters. Refer to Quick Beginnings for information on the OIA indicators.

To translate the returned data into OIA graphics characters, proceed as follows:

1. Print the data returned in bytes 2 through 81 to the screen or to a printer.
2. Using the code page chart applicable to the device on which the output appears, find the hexadecimal value corresponding to each character.
3. Using Figure 2, find the OIA graphics character corresponding to each hexadecimal value found in step 2.

The online and screen ownership group images are for non-SNA 3274 controller configurations. For SNA, the CD hex value is translated by CD (see Figure 2). If running on a 3174 controller or SDLC connection, the hex value X'F4' is replaced by X'B2' or X'22'. The highlight indicator is a corresponding image (in the first 80 bytes of the data string) of the "Group 5 (offset 86: Highlight group 1" byte. The highlight indicator is followed by either X'F9' (blink), X'FC' (underscore), X'D2' (reverse video), or X'80' (host default).

The short session ID followed by X'20' is in column 7.

All group images are represented by Main Frame Interactive (MFI) hex code points.

Figure 2. Host Presentation Space Characters

• Group 1 (Offset 82): Online and Screen Ownership

  Bit	Meaning
  0-1	Reserved
  2	SSCP-LU session owns screen
  3	LU-LU session owns screen
  4	Online and not owned
  5	Subsystem ready
  6-7	Reserved

• Group 2 (Offset 83): Character Selection

  Bit	Meaning
  0	Reserved
  1	APL
  2	Katakana (Japan only)
  3	Alphanumeric
  4-5	Reserved
  6	Hiragana (Japan only)
  7	Double-byte character

• Group 3 (Offset 84): Shift State

  Bit	Meaning
  0	Upper shift
  1	Numeric
  2	CAPS
  3-7	Reserved

• Group 4 (Offset 85): PSS Group 1

  Bit	Meaning
  0-7	Reserved

• Group 5 (Offset 86): Highlight Group 1

  Bit	Meaning
  0	Operator selectable
  1	Field inherit
  2-7	Reserved

• Group 6 (Offset 87): Color Group 1

  Bit	Meaning
  0	Operator selectable
  1	Field inherit
  2-7	Reserved

• Group 7 (Offset 88): Insert

  Bit	Meaning
  0	Insert mode
  1-7	Reserved

• Group 8 (Offset 89-93): Input Inhibited (5 bytes)
  • Byte 1 (Offset 89)

    Bit	Meaning
    0	Non-resettable machine check
    1	Reserved
    2	Machine check
    3	Communications check
    4	Program check
    5-7	Reserved

  • Byte 2 (Offset 90)

    Bit	Meaning
    0	Device busy
    1	Terminal wait
    2	Minus symbol
    3	Minus function
    4	Too much entered
    5-7	Reserved

  • Byte 3 (Offset 91)

    Bit	Meaning
    0-2	Reserved
    3	Incorrect dead key combination, limited key.
    4	Wrong place
    5-7	Reserved

  • Byte 4 (Offset 92)

    Bit	Meaning
    0-1	Reserved
    2	System wait
    3-7	Reserved

  • Byte 5 (Offset 93)

    Bit	Meaning
    0-7	Reserved

• Group 9 (Offset 94): PSS Group 2

  Bit	Meaning
  0-7	Reserved

• Group 10 (Offset 95): Highlight Group 2

  Bit	Meaning
  0-7	Reserved

• Group 11 (Offset 96): Color Group 2

  Bit	Meaning
  0-7	Reserved

• Group 12 (Offset 97): Communication Error Reminder

  Bit	Meaning
  0-6	Communications error
  1-7	Reserved

• Group 13 (Offset 98): Printer State

  Bit	Meaning
  0-7	Reserved

• Group 14 (Offset 99): Graphics

  Bit	Meaning
  0-7	Reserved

• Group 15 (Offset 100): Reserved
• Group 16 (Offset 101): Automatic Key Play/Record State

  Bit	Meaning
  0-7	Reserved

• Group 17 (Offset 102): Automatic Key Quit/Stop State

  Bit	Meaning
  0-7	Reserved

• Group 18 (Offset 103): Expanded State

  Bit	Meaning
  0-7	Reserved

PC400 OIA Group Indicator Meanings and Its Image

Details of the OIA group are listed in the following tables.

• Group 1 (Offset 82): Online and Screen Ownership

  Bit	Meaning	Beginning Position of Data String
  0-2	Reserved
  3	System available	1
  4	Reserved
  5	Subsystem ready
  6-7	Reserved

• Group 2 (Offset 83): Character Selection

  Bit	Meaning	Beginning Position of Data String
  0-1	Reserved
  2	Katakana (Japan only)
  3	Alphanumeric
  4-5	Reserved
  6	Hiragana (Japan only)
  7	Double-byte character

• Group 3 (Offset 84): Shift State

  Bit	Meaning	Beginning Position of Data String
  0	Reserved
  1	Keyboard shift	39
  2	CAPS
  3-6	Reserved
  7	Double-byte character input available

• Group 4 (Offset 85): PSS Group 1

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 5 (Offset 86): Highlight Group 1

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 6 (Offset 87): Color Group 1

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 7 (Offset 88): Insert

  Bit	Meaning	Beginning Position of Data String
  0	Insert mode	68
  1-7	Reserved

• Group 8 (Offset 89-93): Input Inhibited (5 bytes)
  • Byte 1 (Offset 89)

    Bit	Meaning	Beginning Position of Data String
    0-7	Reserved

  • Byte 2 (Offset 90)

    Bit	Meaning	Beginning Position of Data String
    0-7	Reserved

  • Byte 3 (Offset 91)

    Bit	Meaning	Beginning Position of Data String
    0-4	Reserved
    5	Operator input error	64
    6-7	Reserved

  • Byte 4 (Offset 92)

    Bit	Meaning	Beginning Position of Data String
    0-1	Reserved
    2	System wait	64
    3-7	Reserved

  • Byte 5 (Offset 93)

    Bit	Meaning	Beginning Position of Data String
    0-7	Reserved

• Group 9 (Offset 94): PSS Group 2

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 10 (Offset 95): Highlight Group 2

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 11 (Offset 96): Color Group 2

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 12 (Offset 97): Communication Error Reminder

  Bit	Meaning	Beginning Position of Data String
  0	Communications Error
  1-5	Reserved
  7	Message wait	3

• Group 13 (Offset 98): Printer State

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 14 (Offset 99): Graphics

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 15 (Offset 100): Reserved
• Group 16 (Offset 101): Automatic Key Play/Record State

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 17 (Offset 102): Automatic Key Quit/Stop State

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

• Group 18 (Offset 103): Expanded State

  Bit	Meaning	Beginning Position of Data String
  0-7	Reserved

VT Host OIA Group Indicator Meanings and Its Image

Details of the VT Host OIA group are listed in the following tables.

• Group 1 (Offset 82): Online and Screen Ownership

  Bit	Meaning
  5	Subsystem ready

• Group 2 (Offset 83): Character Selection

  Bit	Meaning
  0	Upper shift
  2	CAPS

• Group 7 (Offset 88): Insert

  Bit	Meaning
  0	Insert mode

Some columns on the OIA line display different messages for VT than those messages displayed for 3270/5250. See the following table for specific details.

Copy Presentation Space (5)

The Copy Presentation Space function copies the contents of the host-connected presentation space into a data string that you define in your EHLLAPI application program.

The Copy Presentation Space function translates the characters in the host source presentation space into ASCII. Attribute bytes and other characters not represented in ASCII normally are translated into blanks. If you do not want the attribute bytes translated into blanks, you can override this translation with the ATTRB option under the Set Session Parameters (9) function.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a data string, length, and a return code.

Data String:

Contents of the connected host presentation space.

Length:

Length of the data copied.

Return Code:

The following codes are defined:

Notes on Using This Function

1. An EAB can be returned when the Set Session Parameters (9) function EAB option is used. EAB is related to each character in the presentation space and is returned preceding each character.
2. DBCS Only: The Set Session Parameters (9) function EAD option is used with this function to return a 2-byte EAD. If the EAD option is specified instead of the EAB option, EAD is returned preceding each character. If both the EAB and EAD options are specified, EAD is returned preceding the EAB.

   If the start position of the copy is at the second byte in the double-byte character, or the end position is at the first byte in the double-byte character, the bytes are translated into blanks.

3. The Copy Presentation Space function is affected by the following session options:
   • ATTRB/NOATTRB/NULLATTRB
   • EAB/NOEAB
   • XLATE/NOXLATE
   • BLANK/NOBLANK
   • DISPLAY/NODISPLAY
   • EAD/NOEAD (for DBCS only)
   • NOSO/SPACESO/SO (for DBCS only)
   • EXTEND_PS/NOEXTEND_PS

Refer to items 5; 13, 14, 15 and 17; and 20 and 21 for more information.

If the target data string provided is not long enough to hold the requested data, unpredictable results can occur.

As previously stated, the return of attributes by the various Copy (5, 8, and 34) functions is affected by the Set Session Parameters (9) function. The involved set session parameters have the following effect:

Set Session Parameter

Effect on the COPY Function

NOEAB and NOEAD

Attributes are not returned. Only text is copied from the presentation space to the user buffer.

EAB and NOXLATE

Attributes are returned as defined in the following tables.

EAB and XLATE

The colors used for the presentation space display are returned. Colors can be remapped; so the attribute colors are not the ones returned by the Copy functions when XLATE and EAB are on at the same time.

EAD

Double-byte character set attributes are returned as shown in the following tables.

NOSO/SPACESO/SO

When NOSO is specified, it works as SPACESO. The size of the presentation space is not changed.

The returned character attributes are defined in the following tables. The attribute bit positions are in IBM format with bit 0 the left most bit in the byte.

3270 character attributes are returned from the host to the emulator. The following table applies when EAB and NOXLATE are set.

5250 character attributes are returned from the host to the emulator. The following table applies when EAB and NOXLATE are set.

The following table shows Personal Communications character color attributes. The following table applies when EAB and XLATE are set.

• Double-byte character set attributes (for DBCS only)
  • The first byte

    Bit Position	Character Position	Field Attribute Position
    0	Double-byte character	Reserved
    1	The first byte of the double-byte character	Reserved
    2	SO	Reserved
    3-4	SI (Bit position 3)	5250 DBCS related field When the value of bit position 7 is 0: 00 = Default 01 = DBCS only 10 = Either DBCS or SBCS 11 = Mixture of DBCS and SBCS When the value of bit position 7 is 1: 00 = Reserved 01 = DBCS only without SO/SI 10 = Reserved 11 = Reserved
    5	Reserved	SO/SI enabled (3270 only)
    6	Reserved	Character attributes exist (3270 only)
    7	Reserved	5250 DBCS related extended field 0 = Basic double-byte field 1 = Extended double-byte field

  • The second byte

    Bit Position	Character Position	Field Attribute Position
    0	Reserved	Left grid line (3270 only)
    1	Reserved	Upper grid line (3270 only)
    2	Reserved	Right grid line (3270 only)
    3	Reserved	Under grid line (3270 only)
    4	Left grid line	Left grid line
    5	Upper grid line	Upper grid line
    6-7	Reserved	Reserved

For a PS/2 monochrome display, the characters in the application (workstation) session appear as various shades of gray. This is required to give users their remapped colors in the EHLLAPI application session so they can get what they see in their host application presentation spaces.

If you want to copy only a portion of the host presentation space, use the Copy Presentation Space to String (8) function.

To use this function, preallocate memory to receive the returned data string parameter. The statements required to preallocate this memory vary depending on the language in which your application is written. Refer to Memory Allocation for more information.

1390/1399 Code Page Support

Unicode functionality is supported only on 3270 and 5250 sessions.

In a Unicode session, the characters in the host source presentation space are translated into Unicode. Attribute bytes are normally translated into blanks.

The XLATE option (that can be specified using the Set Session Parameters (9) function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a data string and a return code.

Data String:

String containing the Unicode representation of the contents of presentation space is returned

Return Code:

The following codes are defined:

Notes on Using This Function

The following options are supported in a Unicode session for Copy Presentation Space (5) and function in the same way as in DBCS:

• NOATTRB
• ATTRB
• NULLATTRB
• EAB
• NOEAB
• NOXLATE
• DISPLAY
• NODISPLAY
• BLANK
• NOBLANK

1137 Code Page Support

Unicode functionality is supported only on 5250 sessions.

In a Unicode session, the characters in the host source presentation space are translated into Unicode. Attribute bytes are normally translated into blanks.

The XLATE option (that can be specified using the Set Session Parameters (9) function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a data string and a return code.

Data String:

String containing the Unicode representation of the contents of presentation space is returned

Return Code:

The following codes are defined:

Notes on Using This Function

The following options are supported in a Unicode session for Copy Presentation Space (5) and function in the same way as in SBCS:

• NOATTRB
• ATTRB
• NULLATTRB
• EAB
• NOEAB
• NOXLATE
• DISPLAY
• NODISPLAY
• BLANK
• NOBLANK

Copy Presentation Space to String (8)

The Copy Presentation Space to String function is used to copy all or part of the host-connected presentation space into a data string that you define in your EHLLAPI application program.

The input PS position is the offset into the host presentation space. This offset is based on a layout in which the upper-left corner (row 1/column 1) is location 1 and the bottom-right corner is 3564, which is the maximum screen size for the host presentation space. The value of PS Position + (Length - 1) cannot exceed the configured size of your host presentation space.

The Copy Presentation Space to String function translates the characters in the host source presentation space into ASCII. Attribute bytes and other characters not represented in ASCII normally are translated into blanks. If you do not want the attribute bytes translated into blanks, you can override this translation with the ATTRB option under the Set Session Parameters (9) function.

Prerequisite Calls

Connect Presentation Space (1).

Call Parameters

Return Parameters

This function returns a data string and a return code.

Data String:

Contents of the host presentation space.

Return Code:

The following codes are defined:

Notes on Using This Function

1. An EAB can be returned when the Set Session Parameters (9) function EAB option is used. EAB is related to each character in the presentation space and is returned following each character.
2. DBCS Only: The Set Session Parameters (9) function EAD option is used with this function to return a 2-byte EAD. If the EAD option is specified instead of the EAB option, EAD is returned preceding each character. If both the EAB and EAD options are specified, EAD is returned following the EAB.

   If the start position of the copy is at the second byte in the double-byte character, or the end position is at the first byte in the double-byte character, the bytes are translated into blanks. If the EAD option is set to on, three bytes are returned for each character. If both the EAB and EAD options are set to on, four bytes are returned for each character.

3. The Copy Presentation Space to String function is affected by the following options:
   • ATTRB/NOATTRB/NULLATTRB
   • EAB/NOEAB
   • XLATE/NOXLATE
   • BLANK/NOBLANK
   • DISPLAY/NODISPLAY
   • EAD/NOEAD (for DBCS only)
   • NOSO/SPACESO/SO (for DBCS only)
   • EXTEND_PS/NOEXTEND_PS
   Refer to items 5; 13 and 14; 15; 17; and 20 and 21

   If the target data string provided is not large enough to hold the requested number of bytes, the copy ends successfully (RC=0, 4, or 5) when the end of the target data string is reached.

   As previously stated, the return of attributes by the various Copy (5, 8, and 34) functions is affected by the Set Session Parameters (9) function. The involved set session parameters have the following effect:

   Set Session Parameter

   Effect on the Copy Function

   NOEAB and NOEAD

   Attributes are not returned. Only text is copied from the presentation space to the user buffer.

   EAB and NOXLATE

   Attributes are returned as defined in the following tables.

   EAB and XLATE

   The colors used for the presentation space display are returned. Colors can be remapped, so the attribute colors are not the ones returned by the Copy functions when XLATE and EAB are on at the same time.

   EAD

   Double-byte character set attributes are returned as shown in the following tables.

   The returned character attributes are defined in the following tables. The attribute bit positions are in IBM format with bit 0 the left most bit in the byte.

   • 3270 character attributes are returned from the host to the emulator. The following table applies when EAB and NOXLATE are set.

   Bit Position	Meaning
   0-1	Character highlighting 00 = Normal 01 = Blink 10 = Reverse video 11 = Underline
   2-4	Character color (Color remap can override this color definition.) 000 = Default 001 = Blue 010 = Red 011 = Pink 100 = Green 101 = Turquoise 110 = Yellow 111 = White
   5-7	Reserved

   • 5250 character attributes are returned from the host to the emulator. The following table applies when EAB and NOXLATE are set.

   Bit Position	Meaning
   0	Reverse image 0 = Normal image 1 = Reverse image
   1	Underline 0 = No underline 1 = Underline
   2	Blink 0 = Not blink 1 = Blink
   3	Separator of columns 0 = No separator 1 = Separator
   4-7	Reserved

   • VT character attributes are returned from the host to the emulator. The following table applies when EAB and NOXLATE are set.

   Bit Position	Meaning
   0-3	Reserved
   4	Bold 1 = On 0 = Off
   5	Underscore 1 = On 1 = Off
   6	Blink 1 = On 0 = Off
   7	Reverse 0 = On 1 = Off

   • The following table shows Personal Communications character color attributes. The following table applies when EAB and XLATE are set.

   Bit Position	Meaning
   0-3	Background character colors 0000 = Black 0001 = Blue 0010 = Green 0011 = Cyan 0100 = Red 0101 = Magenta 0110 = Brown (3270), Yellow (5250) 0111 = White
   4-7	Foreground character colors 0000 = Black 0001 = Blue 0010 = Green 0011 = Cyan 0100 = Red 0101 = Magenta 0110 = Brown (3270), Yellow (5250) 0111 = White 1000 = Gray 1001 = Light blue 1010 = Light green 1011 = Light cyan 1100 = Light red 1101 = Light magenta 1110 = Yellow 1111 = White (high intensity)

   • Double-byte character set attributes
     • The first byte

       Bit Position	Character Position	Field Attribute Position
       0	Double-byte character	Reserved
       1	The first byte of the double-byte character	Reserved
       2	SO	Reserved
       3-4	SI (Bit position 3)	5250 DBCS related field When the value of bit position 7 is 0: 00 = Default 01 = DBCS only 10 = Either DBCS or SBCS 11 = Mixture of DBCS and SBCS When the value of bit position 7 is 1: 00 = Reserved 01 = DBCS only without SO/SI 10 = Reserved 11 = Reserved
       5	Reserved	SO/SI enable (3270 only)
       6	Reserved	Character Attributes exist (3270 only)
       7	Reserved	5250 DBCS related extended field 0 = Basic double-byte field 1 = Extended double-byte field

     • The second byte

       Bit Position	Character Position	Field Attribute Position
       0	Reserved	Left grid line (3270 only)
       1	Reserved	Upper grid line (3270 only)
       2	Reserved	Right grid line (3270 only)
       3	Reserved	Under grid line (3270 only)
       4	Left grid line	Left grid line
       5	Upper grid line	Upper grid line
       6-7	Reserved	Reserved

   For a PS/2 monochrome display, the characters in the application (workstation) session appear as various shades of gray. This is required to give users their remapped colors in the EHLLAPI application session so they can get what they see in their host application presentation spaces.

4. To use this function, preallocate memory to receive the returned data string parameter. The statements required to preallocate this memory vary depending on the language in which your application is written. Refer to Memory Allocation for more information.

1390/1399 Code Page Support

Unicode functionality is supported only on 3270 and 5250 sessions.

In a Unicode session, the characters in the host source presentation space are translated into Unicode. Attribute bytes are normally translated into blanks.

The XLATE option (that can be specified using the Set Session Parameters (9) function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a data string and a return code.

Data String:

String containing the Unicode data is returned

Return Code:

The following codes are defined:

Notes on Using This Function

The following options are supported in a Unicode session for Copy Presentation Space to String and function in the same way as in DBCS:

• NOATTRB
• ATTRB
• NULLATTRB
• EAB
• NOEAB
• NOXLATE
• DISPLAY
• NODISPLAY
• BLANK
• NOBLANK

1137 Code Page Support

Unicode functionality is supported only on 5250 sessions.

In a Unicode session, the characters in the host source presentation space are translated into Unicode. Attribute bytes are normally translated into blanks.

The XLATE option (that can be specified using the Set Session Parameters (9) function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a data string and a return code.

Data String:

Contents of the host presentation space.

Return Code:

The following codes are defined:

Notes on Using This Function

The following options are supported in a Unicode session for Copy Presentation Space to String and function in the same way as in SBCS:

• NOATTRB
• ATTRB
• NULLATTRB
• EAB
• NOEAB
• NOXLATE
• DISPLAY
• NODISPLAY
• BLANK
• NOBLANK

Copy String to Field (33)

The Copy String to Field function transfers a string of characters into a specified field in the host-connected presentation space. This function can be used only in a field-formatted host presentation space.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

Notes on Using This Function

1. The Copy String to Field function is affected by the following options:
   • STRLEN/STREOT
   • EOT
   • EAB/NOEAB
   • XLATE/NOXLATE
   • PUTEAB/NOPUTEAB

   Refer to items 1 and 2; 13 and 14; 18; and 20 and 21 for more information.

2. The string to be transferred is specified with the calling data string parameter. The string ends when one of these three conditions is encountered:
   • When an end-of-text (EOT) delimiter is encountered in the string if EOT mode was selected using the Set Session Parameters (9) function. (See Set Session Parameters (9)).
   • When the number specified in the length is reached if not in EOT mode.
   • When an end-of-field is encountered in the field.
   Note:

   If the field at the end of the host presentation space wraps, wrapping occurs when the end of the presentation space is reached.
3. The keyboard mnemonics (see Send Key (3) function) cannot be sent using the Copy String to Field function.
4. The first byte of the data to be transferred is always placed at the beginning of the field that contains the specified PS position.
5. DBCS Only: Double-byte characters can be included as a part of the string.
   Note:

   PC400 does not add SO and SI to the string. When you write the strings, including double-byte characters at the DBCS mixed field, generate SO and SI and create the area where double-byte characters are written by using the Send Key (3) function in advance.

   If both single-byte and double-byte characters exist in a string, the data might be truncated because the data length in EBCDIC is longer than in JISCII. In this case, only the first byte or the second byte of the double-byte character is not written.

   If the last character in the original string is the first byte of the double-byte character, the character is not written and not counted in the length.

   A control character is converted from single-byte character to double-byte character, or from double-byte character to single-byte character depending on the field condition. A pair of NULL+Control Character between SO and SI is treated as a double-byte control character. For example, the following strings are copied into the single-byte character field or the double-byte character field:

   String	Meanings	Single-byte character field	Double-byte character field
   X'000C'	(NULL)(FF) X'00'X'0C'	(SB NULL)(SB FF) X'00'X'0C'	(DB NULL)(DB FF) X'0000'X'000C'
   X'0E000C0F'	(SO)(DB FF)(SI) X'0E'X'000C'X'0F'	-S error	(DB FF) X'000C'
   Note: SB means single-byte characters and DB means double-byte characters.

1390/1399 Code Page Support

Unicode functionality is supported only on 3270 and 5250 sessions.

STREOT option is not supported in a Unicode session. Please refer to Set Session Parameters (9) for details.

The XLATE option (that can be specified using the Set Session Parameters (9) function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

Notes on Using This Function

The following options are supported in a Unicode session for Copy String to Field and function in the same way as in DBCS:

• STRLEN
• EAB
• NOEAB
• NOXLATE
• PUTEAB
• NOPUTEAB

1137 Code Page Support

Unicode functionality is supported only on 5250 sessions.

STREOT option is not supported in a Unicode session. Please refer to Set Session Parameters (9) for details.

The XLATE option (that can be specified using the Set Session Parameters (9) function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

Notes on Using This Function

The following options are supported in a Unicode session for Copy String to Field and function in the same way as in SBCS:

• STRLEN
• EAB
• NOEAB
• NOXLATE
• PUTEAB
• NOPUTEAB

Copy String to Presentation Space (15)

The Copy String to Presentation Space function copies an ASCII data string directly into the host presentation space at the location specified by the PS position calling parameter.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

Notes on Using This Function

1. The Copy String to Presentation Space function is affected by the following options:
   • STRLEN/STREOT
   • EOT
   • EAB/NOEAB
   • XLATE/NOXLATE
   • PUTEAB/NOPUTEAB
   • EAD/NOEAD (for DBCS only)
   • NOSO/SPACESO/SO (for DBCS only)
   • EXTEND_PS/NOEXTEND_PS
   Refer to items 1 and 2; 13 and 14; 18; and 20 and 21 for more information.
2. The keyboard mnemonics (see Send Key (3) function) cannot be sent using the Copy String to Presentation Space function.
3. The string ends when an end-of-text (EOT) delimiter is encountered in the string if EOT mode was selected using the Set Session Parameters (9) function. (See Set Session Parameters (9)).
4. Although the Send Key (3) function accomplishes the same purpose, this function responds with the prompt and enters a command more quickly. Because the Send Key (3) function emulates the terminal operator typing the data from the keyboard, its process speed is slow for an application operating with a lot of data. This function provides a faster input path to the host.
5. The original data (the copied string) cannot exceed the size of the presentation space.
6. DBCS Only: Double-byte characters can be included as a part of the string.
   Note:

   PC400 does not add SO and SI to the string. When you write the strings, including double-byte characters at the DBCS mixed field, generate SO and SI and create the area where double-byte characters are written by using the Send Key (3) function in advance.

   If both single-byte and double-byte characters exist in a string, the data might be truncated because the data length in EBCDIC is longer than in JISCII. If only the first byte or the second byte of the double-byte character must be written into the string, a blank is written.

   If the last character in the original string is the first byte of the double-byte character, the character is not written and not counted in the length.

   If the character to be written into the last character of the target presentation space is SO/SI or the first byte of the double-byte character, the character is not written and truncated, and not counted in the length.

   A control character is converted from single-byte character to double-byte character, or from double-byte character to single-byte character depending on the field condition. A pair of NULL+Control Character between SO and SI is treated as a double-byte control character. For example, the following strings are copied into the single-byte character field or the double-byte character field:

   String	Meanings	Single-byte character field	Double-byte character field
   X'000C'	(NULL)(FF) X'00'X'0C'	(SB NULL)(SB FF) X'00'X'0C'	(DB NULL)(DB FF) X'0000'X'000C'
   X'0E000C0F'	(SO)(DB FF)(SI) X'0E'X'000C'X'0F'	-S error	(DB FF) X'000C'
   Note: SB means single-byte characters and DB means double-byte characters.

   Note:

   5250 emulation supports a presentation space of 24 rows by 80 columns. In some instances, Communication Manager 5250 emulation displays a 25th row. This occurs when either an error message from the host is displayed or when the operator selects the SysReq key. Personal Communications always displays the same information on the 24th row. By the EXTEND_PS option, an EHLLAPI application can use the same interface with Communication Manager EHLLAPI and valid presentation space is extended when this condition occurs.
7. This function call may cause a cursor movement to an unexpected position with some host applications. A SendKey function may be a better choice for filling a field than this function.
   Note:

   This only occurs with VT sessions or connections to an ASCII host.

1390/1399 Code Page Support

Unicode functionality is supported only on 3270 and 5250 sessions.

STREOT option is not supported in a Unicode session. Please refer to Set Session Parameters (9) for details.

The XLATE option (that can be specified using the Set Session Parameters (9) function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

Notes on Using This Function

The following options are supported in a Unicode session for Copy String to Presentation Space and function in the same way as in DBCS:

• STRLEN
• EAB
• NOEAB
• NOXLATE
• PUTEAB
• NOPUTEAB

1137 Code Page Support

Unicode functionality is supported only on 5250 sessions.

STREOT option is not supported in a Unicode session. Please refer to Set Session Parameters (9) for details.

The XLATE option (that can be specified using the Set Session Parameters (9) function) is not supported in a Unicode session. This means that even if this option is issued, the EABs will not be translated to the PC color graphics adapter (CGA) format.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

Notes on Using This Function

The following options are supported in a Unicode session for Copy String to Presentation Space and function in the same way as in SBCS:

• STRLEN
• EAB
• NOEAB
• NOXLATE
• PUTEAB
• NOPUTEAB

Copy Presentation Space to Clipboard (35)

The Copy Presentation Space to Clipboard function is used to copy all or part of the host-connected presentation space into clipboard. The input PS position is the offset into the host presentation space. This offset is based on a layout in which the upper-left corner (row 1/column 1) is location 1 and the bottom-right corner is 3564, which is the maximum screen size for the host presentation space. The value of PS Position + (Length - 1) cannot exceed the configured size of your host presentation space.

The Copy Presentation Space to Clipboard translates the characters in the host source presentation space into ASCII. Attribute bytes and other characters not represented in ASCII normally are translated into blanks. If you do not want the attribute bytes translated into blanks, you can override this translation with the ATTRB option under the Set Sesssion Parameters (9) function.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

Notes on Using This Function

1. An EAB can be returned when the Set Session Parameters (9) function EAB option is used. EAB is related to each character in the presentation space and is returned following each character.
2. DBCS Only: The Set Session Parameters (9) function EAD option is used with this function to return a 2-byte EAD. If the EAD option is specified instead of the EAB option, EAD is returned preceding each character. If both the EAB and EAD options are specified, EAD is returned following the EAB. If the start position of the copy is at the second byte in the double-byte character, or the end position is at the first byte in the double-byte character, the bytes are translated into blanks. If the EAD option is set to on, three bytes are returned for each character. If both the EAB and EAD options are set to on, four bytes are returned for each character.
3. The Copy Presentation Space to Clipboard function is affected by the following options:
   • ATTRB/NOATTRB/NULLATTRB
   • EAB/NOEAB
   • XLATE/NOXLATE
   • BLANK/NOBLANK
   • DISPLAY/NODISPLAY
   • PUTEAB/NOPUTEAB
   • EAD/NOEAD (for DBCS only)
   • NOSO/SPACESO/SO (for DBCS only)
   • EXTEND_PS/NOEXTEND_PS
4. The data string buffer is used in processing the data retrieved from presentation space and copy to clipboard. If the data string buffer provided is not large enough to hold the requested number of bytes, the copy ends successfully (RC=0, 4, or 5) when the end of the data string buffer is reached. As previously stated, the return of attributes by the various Copy (5, 8, and 34) functions is affected by the Set Session Parameters (9) function. The involved set session parameters have the following effect:

   Set Session Parameter

   Effect on the Copy Function

   NOEAB and NOEAD

   Attributes are not returned. Only text is copied from the presentation space to the clipboard.

   EAB and NOXLATE

   Attributes are returned as defined in the following tables.

   EAB and XLATE

   The colors used for the presentation space display are returned. Colors can be remapped, so the attribute colors are not the ones returned by the Copy functions when XLATE and EAB are on at the same time.

   EAD

   Double-byte character set attributes are returned as shown in the following tables. The returned character attributes are defined in the following tables. The attribute bit positions are in IBM format with bit 0 the left most bit in the byte. v 3270 character attributes are returned from the host to the emulator. The following table applies when EAB and NOXLATE are set.

Paste Clipboard to Presentation Space (36)

The Paste Clipboard to Presentation Space function pastes an ASCII data string directly into the host presentation space at the location specified by the PS position calling parameter.

Prerequisite Calls

Call Parameters

Return Parameters

Notes on Using This Function

1. The Paste Clipboard to Presentation Space function is affected by the following options:
   • STRLEN/STREOT
   • EAB/NOEAB
   • EOT
   • XLATE/NOXLATE
   • PUTEAB/NOPUTEAB
   • EAD/NOEAD (for DBCS only)
   • NOSO/SPACESO/SO (for DBCS only)
   • EXTEND_PS/NOEXTEND_PS
2. The string ends when an end-of-text (EOT) delimiter is encountered in the string if EOT mode was selected using the Set Session Parameters (9) function. (See "Set Session Parameters (9)" on page 147).
3. The original data (the copied string) cannot exceed the size of the presentation space.
4. DBCS Only: Double-byte characters can be included as a part of the string. Note: PC400 does not add SO and SI to the string. When you paste the strings, including double-byte characters at the DBCS mixed field, generate SO and SI and create the area where double-byte characters are written by using the Send Key (3) function in advance. If both single-byte and double-byte characters exist in a string, the data might be truncated because the data length in EBCDIC is longer than in JISCII. If only the first byte or the second byte of the double-byte character must be written into the string, a blank is written. If the last character in the original string is the first byte of the double-byte character, the character is not written and not counted in the length. If the character to be written into the last character of the target presentation space is SO/SI or the first byte of the double-byte character, the character is not written and truncated, and not counted in the length. A control character is converted from single-byte character to double-byte character, or from double-byte character to single-byte character depending on the field condition. A pair of NULL+Control Character between SO and SI is treated as a double-byte control character. For example, the following strings are copied into the single-byte character field or the double-byte character field:

Note: SB means single-byte characters and DB means double-byte characters.

Note: 5250 emulation supports a presentation space of 24 rows by 80 columns. In some instances, Communication Manager 5250 emulation displays a 25th row. This occurs when either an error message from the host is displayed or when the operator selects the SysReq key. Personal Communications always displays the same information on the 24th row. By the EXTEND_PS option, an EHLLAPI application can use the same interface with Communication Manager EHLLAPI and valid presentation space is extended when this condition occurs.

Disconnect from Structured Fields (121)

The Disconnect from Structured Fields function drops the connection between the emulation program and the EHLLAPI application. The EHLLAPI application must disconnect from the emulation program before exiting from the system. The EHLLAPI application should issue this function request if a previous Connect for Structured Fields was issued.

The Reset System (21) function will also disconnect any outstanding SF connections.

Prerequisite Calls

Connect for Structured Fields (120)

Call Parameters

Data String Contents

Return Parameters

Notes on Using This Function

1. When a Disconnect from Structured Fields function is called, any outstanding asynchronous Read Structured Fields (126) or Write Structured Fields (127) function requests are returned if the application issues the Get Request Completion (125) function call. Use the asynchronous form of this function when cleaning up after issuing a Disconnect call.
2. The Reset System (21) function will also free any outstanding asynchronous requests (requests that have not been retrieved by the application using the Get Request Completion (125) function).

Disconnect Presentation Space (2)

The Disconnect Presentation Space function drops the connection between your EHLLAPI application program and the host presentation space. Also, if a host presentation space is reserved using the Reserve (11) function, it is released upon execution of the Disconnect Presentation Space function.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

Notes on Using This Function

1. After the Disconnect Presentation Space function is called, functions that interact with the host-connected presentation space are no longer valid (for example, the Send Key (3), Wait (4), Reserve (11) and Release (12) functions).
2. Your EHLLAPI application should disconnect from the host presentation space before exiting.
3. The Disconnect Presentation Space function does not reset the session parameters to the defaults. Your EHLLAPI application must call the Reset System (21) function to accomplish this.

Disconnect Window Service (102)

The Disconnect Window Service function disconnects the window services connection between the EHLLAPI program and the specified host presentation space window.

Prerequisite Calls

Connect Window Services (101)

Call Parameters

Data String Contents

Return Parameters

Notes on Using This Function

After the Disconnect Window Service function has been called, your application no longer manages the presentation space window.

Before exiting the application, you should request a Disconnect Window Service function for all presentation spaces that have been connected for Presentation Manager services. If the application exits with an outstanding connection for window services, the subsystem cancels the outstanding connection.

EditKey Intercept

This feature enables you to intercept Edit keys in addition to the existing all keystrokes and send them to a session in a Windows 32-bit environment.

Prerequisites

1. Map the Edit functions in the Customize Keyboard window (for example Ctrl+C for edit copy function).
2. Call the Start Keystroke Intercept (50) EHLLAPI function with the call parameter data string value set. The values are as follows:

   Byte Position	Contents
   1	One of the following values: A specific host presentation space short name (PSID) A blank or null indicating a request for the host-connected host presentation space
   2 to 4	Reserved
   5	An option code character: D for AID keystrokes only L for all keystrokes E for all keystrokes and Edit keys M for requesting the asynchronous message mode of the notification (Windows only). If M is specified, a code character D or L, or E must be placed in position 13
   6 to 8	Reserved
   9 to 12	If M is specified in position 5, the window handle of the window that receives the message. The message is a non-zero return value of RegisterWindowMessage (PCSHLL).
   13	If M is specified in position 5, one of the following values: D for AID keystrokes only L for all keystrokes E for all keystrokes and Edit keys
   14 to 16	Reserved

3. To get the intercepted Edit keys, use the Get Key (51) EHLLAPI function. The key mnemonic returned in the data string for the Edit keys will have M (keystroke type mnemonic) at the 5th byte position. The next 4 bytes will have one of the following Edit key mnemonics based on the Edit key intercepted:

   Key mnemonic	Key intercepted
   @W@C	Edit Copy
   @W@D	Edit Clear
   @W@E	Edit Copy Append
   @W@L	Edit Copy Link
   @W@N	Edit Paste Next
   @W@V	Edit Paste
   @W@X	Edit Cut
   @W@Z	Edit Undo

4. To send Edit keys to the session, use the Send Key (3) EHLLAPI function. The data string passed as the call parameter can specify the following Edit key mnemonics:

   Key mnemonic	Key sent
   @W@C	Edit Copy
   @W@D	Edit Clear
   @W@E	Edit Copy Append
   @W@L	Edit Copy Link
   @W@N	Edit Paste Next
   @W@V	Edit Paste
   @W@X	Edit Cut
   @W@Z	Edit Undo

Find Field Length (32)

The Find Field Length function returns the length of a target field in the connected presentation space. This function can be used to find either protected or unprotected fields, but only in a field-formatted host presentation space.

This function returns the number of characters contained in the field identified using the call PS position parameter. This includes all characters from the beginning of the target field up to the character preceding the next attribute byte.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

The calling 2-character data string can contain:

Return Parameters

This function returns a length and a return code.

Length:

The following lengths are valid:

Return Code:

The following codes are defined:

Notes on Using This Function

Except when    or T  is used as the calling data string, if the field found is the same as the field from which the Find started, a return code of 24 is returned.

Find Field Position (31)

The Find Field Position function returns the beginning position of a target field in the host-connected presentation space. This function can be used to find either protected or unprotected fields but only in a field-formatted host presentation space.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

The calling 2-character data string can contain:

Return Parameters

This function returns a length and a return code.

Length:

The following lengths are valid:

Return Code:

The following codes are defined:

Notes on Using This Function

Except when    or T  is used as the calling data string, if the field found is the same as the field from which the Find started, a return code of 24 is returned.

Free Communications Buffer (124)

The Free Communications Buffer function returns to management memory a buffer that is no longer required by the application. The application should free the buffer prior to exiting the system.

Prerequisite Calls

Allocate Communications Buffer (123)

Call Parameters

Data String Contents

Return Parameters

Notes on Using This Function

1. If the application attempts to free an in use buffer, the free request will be denied and a return code of 41 will be returned.
2. An application should request the Free Communications Buffer (124) function before exiting for all communication buffers that have been allocated using the Allocate Communications Buffer (123) function.
3. The Reset System (21) function will free buffers allocated by the Allocate Communications Buffer (123) function.

Get Key (51)

The Get Key function lets your EHLLAPI application program retrieve a keystroke from a session specified by the Start Keystroke Intercept (50) function and either process, accept, or reject that keystroke. By placing this function in a loop, you can use it to intercept a string.

Prerequisite Calls

Start Keystroke Intercept (50)

Call Parameters

Data String Contents

Return Parameters

This function returns a data string and a return code.

Data String:

See the following table:

For clarification, some examples of returned data strings are provided below:

16-Bit Interface

EAt

E is the presentation space short name. The keystrokes are returned as ASCII (A), and the returned key is the lowercase letter t. (Bytes 4-8 = X'00').

EM@2

E is the presentation space short name. The keystrokes are returned as mnemonics, and the returned key is PF2 (Bytes 5-8 = X'00').

32-Bit Interface

E   At

E is the presentation space short name. The keystrokes are returned as ASCII (A), and the returned key is the lowercase letter t. (Bytes 7-11 = X'00').

E   M@2

E is the presentation space short name. The keystrokes are returned as mnemonics, and the returned key is PF2 (Bytes 8-11 = X'00').

Return Code:

The following codes are valid:

Notes on Using This Function

1. If a return code of 31 occurs for the Get Key function, either:
   • Increase the value of the calling length parameter for the Start Keystroke Intercept (50) function, or
   • Execute the Get Key function more frequently.

   An intercepted keystroke occupies 3 bytes in the buffer. The next intercepted keystroke is placed in the adjacent three bytes. When the Get Key function retrieves a keystroke (first in first out, FIFO), the three bytes that it occupied are made available for another keystroke. By increasing the size of the buffer or the rate at which keystrokes are retrieved from the buffer, you can eliminate buffer overflow.

   For the PC/3270, another way to eliminate return code 31 is to operate the PC/3270 emulator in the resume mode.

2. You can use the Send Key (3) function to pass both original keystrokes and any others that your EHLLAPI application might need to the host-connected presentation space.
3. Keystrokes arrive asynchronously and are enqueued in the keystroke queue that you have provided in your EHLLAPI application program using the Start Keystroke Intercept (50) function.
4. The Get Key function behaves like a read. When keystrokes are available, they are read into the data area that you have provided in your application.
5. In the case of field support for a session, the application might be interested only in AID keys, for example the Enter key. If so, the Start Keystroke Intercept (50) function option code should be set to D (meaning for AID Keys only).
6. To use this function, preallocate memory to receive the returned data string parameter. The statements required to preallocate this memory vary depending on the language in which your application is written. Refer to Memory Allocation for more information.

1390/1399 Code Page Support

Unicode functionality is supported only on 3270 and 5250 sessions.

The session option ESC is not supported in a Unicode session; using this option you cannot set a Unicode character as an ESC character. Use the default ESC character @ in a Unicode session. See Set Session Parameters (9) for details.

Prerequisite Calls

Start Keystroke Intercept (50)

Call Parameters

Data String Contents

Return Parameters

This function returns a data string and a return code.

Data String:

See the following table for 32-bit interface:

Return Code:

The following codes are valid:

1137 Code Page Support

Unicode functionality is supported only on 5250 sessions.

The session option ESC is not supported in a Unicode session; using this option you cannot set a Unicode character as an ESC character. Use the default ESC character @ in a Unicode session. See Set Session Parameters (9) for details.

Prerequisite Calls

Start Keystroke Intercept (50)

Call Parameters

Data String Contents

Return Parameters

This function returns a data string and a return code.

Data String:

See the following table for 32-bit interface:

Return Code:

The following codes are valid:

Get Request Completion (125)

The Get Request Completion function allows an application to determine the status of a previous asynchronous function request issued to the EHLLAPI and to obtain the function parameter list before using the data string again. This function is valid only if the user specified asynchronous (A) completion on a previous function call such as Read Structured Fields (126) or Write Structured Fields (127).

Each asynchronous request requiring the Get Request Completion function will return a unique ID from the asynchronous request. The application must save this ID. This ID is the identification used by the Get Request Completion function to identify the desired request. The user has three request options using this function:

1. The application can query or wait for a specific asynchronous function request by supplying the request ID of that function and a nonblank session short name.
2. The application can query or wait for the first completed asynchronous function request for a specified session by supplying a request ID of X'0000' and a nonblank session short name.

Prerequisite Calls

Connect Structured Fields (120) and Allocate Communications Buffer (123)

and

Read Structured Fields (126) or Write Structured Fields (127)

Call Parameters

Data String Contents

The Get Request Completion function behaves differently depending upon the second character of the parameter string, which is one of the following characters:

N

Nowait option: If a specific request ID was supplied and the function has completed, control will be returned to the application with a return code of zero and a completed data string as defined in Return Parameters. If a request ID of zero was supplied and any eligible asynchronous function has completed, control will be returned to the application with a return code of zero and a completed data string as defined in Return Parameters.

W

Wait option: If a specific request ID was supplied and the function has not completed, the call will wait until the function has completed before returning to the application. If the supplied request ID was zero and no eligible asynchronous function has completed, the call will wait until a function completes before returning to the calling application. On return, the return code value will be zero and the data string will be completed as defined in Return Parameters.

Return Parameters

There are some differences between return codes 38 and 42:

1. Return code 38
   1. If a specific request ID and session were requested, both the session and ID were found but the request is pending (not in a completed state).
   2. If a zero request ID and a specific session were requested, the specified session has pending requests, but they are not satisfied (complete).
   3. If a zero request ID and a blank session were requested, pending requests were found but none were satisfied (complete).
2. Return code 42
   1. If a specific request ID and session were requested, the specific request ID was not found in either a pending or a completed state.
   2. If a zero request ID and a specific session were requested, the specific session contains no pending or completed requests.
   3. If a zero request ID and a blank session were requested, no pending or completed requests were found.

Notes on Using This Function

1. This function is valid only if the user specified asynchronous completion (A for Asynchronous) on a previous function call such as Read Structured Fields or Write Structured Fields.
2. If the return code is a 0, the application should check the returned data string for information pertaining to the completion of the requested asynchronous function.

Lock Presentation Space API (60)

The Lock Presentation Space API function allows the application to obtain or release exclusive control of the presentation space window over other Windows 32-bit applications. While locked, no other application can connect to the presentation space window.

Successful processing of this function with the Lock causes EHLLAPI presentation space window functions requested from other EHLLAPI applications to be queued until the requesting application unlocks the presentation space. Requests from the locking application are processed normally.

Prerequisite Calls

Connect to Presentation Space (1)

Call Parameters

Data String Contents

Return Parameters

Notes on Using This Function

The following EHLLAPI functions are queued when a lock is in effect:

• Send Key (3)
• Copy Presentation Space (5)
• Search Presentation Space (6)
• Copy Presentation Space to String (8)
• Release (11)
• Reserve (12)
• Query Field Attribute (14)
• Copy String to Presentation Space (15)
• Search Field (30)
• Find Field Position (31)
• Find Field Length (32)
• Copy String to Field (33)
• Copy Field to String (34)
• Set Cursor (40)
• Send File (90)
• Copy Presentation Space to Clipboard (35)
• Paste Clipboard to Presentation Space (36)
• Receive File (91)
• Connect to Presentation Space (1) with the CONPHYS parameter set in a previous Set Sessions Parameter (9) function call.

These queued requests are not serviced until the lock is removed. When the lock is removed, the queued requests are processed in first-in-first-out (FIFO) order. EHLLAPI functions not listed are run as if there was no lock. The requesting application unlocks the presentation space window by one of the following methods:

• Disconnecting from the presentation space while still owning the Lock.
• Issuing the Reset System (21) function while still owning the Lock.
• Stopping the application while still owning the Lock.
• Stopping the session.
• Successfully issuing the Lock Presentation Space API with the Unlock option.

Before exiting the application, you should unlock any presentation space windows that have been locked with the Lock Presentation Space API function. If the application exits with outstanding locks, or a Reset System (21), or Disconnect Presentation Space (2) function is issued, the locks are released.

It is recommended that applications lock the presentation space only for short periods of time and only when exclusive use of the presentation space is required.

Lock Window Services API (61)

The Lock Window Services API function allows the application to obtain or release exclusive control of the presentation space window over other Windows 32-bit applications. While locked, no other application can connect to the presentation space window.

Successful processing of this function with the Lock causes EHLLAPI presentation space window functions requested from other EHLLAPI applications to be queued until the requesting application unlocks the presentation space. Requests from the locking application are processed normally.

Prerequisite Calls

Connect Window Services (101)

Call Parameters

Data String Contents

Return Parameters

Notes on Using This Function

The following EHLLAPI functions are queued when a lock is in effect:

• Window Status (104)
• Change Switch List Name (105)
• Change PS Window Name (106)

These queued requests are not serviced until the lock is removed. When the lock is removed, the queued requests are processed in first-in-first-out (FIFO) order.

The requesting application unlocks the presentation space window by one of the following methods:

• Successfully issuing the Lock Window Services API with the UNLOCK option.
• Disconnecting from the presentation space while still owning the Lock.
• Issuing the Reset System (21) function while still owning the Lock.
• Stopping the application while still owning the Lock.
• Stopping the session.

Before exiting the application, you should Unlock any presentation space windows that have been locked with the Lock Window Services API function. If the application exits with outstanding locks, the subsystem releases the locks.

It is recommended that applications lock the presentation space only for short periods of time and only when exclusive use of the presentation space is required.

Pause (18)

The Pause function waits for a specified amount of time. It should be used in place of timing loops to wait for an event to occur. A Pause function can be ended by a host event if a prior Start Host Notification (23) function has been called and the IPAUSE option is selected.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

Return Parameters

Notes on Using This Function

1. Selecting the FPAUSE or IPAUSE option using the Set Session Parameters (9) function affects the length of the pause you get when you call this function. See item 6 for more information.
2. The value entered in the calling length parameter is the maximum number of half-second intervals that the Pause function waits. For a pause of 20 seconds, a hex value of 0028 (decimal 40) must be passed in the calling length parameter.
3. If you use the IPAUSE option and the pause value is zero, then the function waits up to 2400 half-second intervals, unless interrupted sooner. If you use the FPAUSE option and the pause value is zero, then the function returns immediately.
4. If you use the IPAUSE option, once a pause has been satisfied by a host event, you should call the Query Host Update (24) function to clear the queue prior to the next Pause function. The Pause function will continue to be satisfied with the pending event until the Query Host Update (24) function is completed.
5. A practical maximum value for the Pause function is 2400. You should not use the Pause function for these kinds of tasks:
   • Delay for very long durations (of several hours, for example).
   • Delay for more than a moderate length of time (20 minutes) before checking the system time-of-day clock and proceeding with your EHLLAPI program execution.
   • With applications requiring a high-resolution timer because the time interval created by a Pause function is approximate.
   • Set the time interval to zero in a loop.
6. IPAUSE set and the interruptible pause allow an EHLLAPI application to determine whether the specified host presentation space (PS) or operator information area (OIA) is updated. The following three functions are used:
   • Start Host Notification (23)
   • Query Host Update (24)
   • Stop Host Notification (25)

   By using IPAUSE when the Start function is called, you can make an application wait until the host presentation space or OIA (or both) receives an update. When the receive is completed and the application can issue the Query function to determine the changes, Pause terminates. Then the application issues the Search Presentation Space (6) to check whether the expected update occurred.

Post Intercept Status (52)

The Post Intercept Status function informs the Personal Communications emulator that a keystroke obtained through the Get Key (51) function was accepted or rejected. When the application rejects a keystroke, the Post Intercept Status function issues a beep.

Prerequisite Calls

Start Keystroke Intercept (50)

Call Parameters

The calling data string can contain:

Return Parameters

Query Additional Field Attribute (45)

The Query Additional Field Attribute function returns additional information about the 5250 field containing the input host presentation space position. This information is returned in the data string parameter in the form of a defined structure.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

The calling data string can contain:

Return Parameters

This function returns a data string and a return code.

Data String:

The function returns the following data string.

Byte	Definition
1-6	Reserved
7-8	Two 8-bit unsigned characters that return: R if field is RTL and L if field is LTR. U if field is upper case and L if field is a normal case field.

Return Code:

The following return codes are defined:

Query Close Intercept (42)

The Query Close Intercept function allows the application to determine if the close option was selected.

Prerequisite Calls

Start Close Intercept (41)

Call Parameters

The calling data string can contain:

Return Parameters

Query Communications Buffer Size (122)

The Query Communications Buffer Size function allows an application to determine both the maximum and the optimum buffer sizes supported by the emulation program.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

The calling data string can contain:

Return Parameters

Notes on Using This Function

1. There is no way to require the user to use this function. It is not a required function so that the application can be tailored to run on any system.
2. The buffer sizes returned represent the record sizes that are actually transmitted across the medium. For a DDM connection, the 8-byte header supplied in the Read and Write Structured Fields data buffer is stripped off and 1 byte containing the structured field AID value is prefixed. The application should compare the size of the actual data in the data buffer (which does not include the 8-byte header) with the buffer sizes returned by the Query Communications Buffer Size minus 1 byte. For destination/origin connections, the 8-byte header supplied in the Read and Write Structured Fields data buffer is stripped off and 9 bytes are then prefixed to the data. The application should compare the size of the actual data in the data buffer (which does not include the 8-byte header) with the buffer size returned by the Query Communications Buffer Size minus 9 bytes.
3. The maximum buffer sizes returned represent the maximum number of bytes supported by the workstation hardware and by the emulator. The maximum buffer size can be used only if the host is also configured to accept at least these maximum sizes.
4. The optimum buffer sizes returned represent the optimum number of bytes supported by the both the workstation hardware and the emulator. Some network configurations might set transmission limits smaller than these values. In these cases, the data transfer buffer size override value in the emulator configuration profile will be used for structured field support. The Query Communications Buffer Size will reflect any buffer size override values entered in the emulator configuration profile.

Query Communication Event (81)

The Query Communication Event function lets the EHLLAPI program determine whether any communication events have occurred.

Prerequisite Calls

Start Communication Notification (80)

Call Parameters

The calling data structure contains these elements:

Return Parameters

Query Cursor Location (7)

The Query Cursor Location function indicates the position of the cursor in the host-connected presentation space by returning the cursor position.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a length and a return code.

Length:

Host presentation space position of the cursor.

Return Code:

The following codes are defined:

Query Field Attribute (14)

The Query Field Attribute function returns the attribute byte of the field containing the input host presentation space position. This information is returned in the returned length parameter.

For the PC/3270, note also that:

• The returned length parameter is set to 0 if the screen is unformatted.
• Attribute bytes are equal to or greater than hex C0.

Prerequisite Calls

Connect Presentation Space (1)

Call Parameters

Return Parameters

This function returns a length and a return code.

Length:

The attribute value if the screen is formatted, or 0 if the screen is unformatted.

Return Code:

The following codes are defined:

Notes on Using This Function

The returned field attributes are defined in the following tables. The bit positions are in IBM format with bit 0 as the left most bit in the byte.

• 3270 field attribute:

• 5250 field attributes:

Query Host Update (24)

The Query Host Update function lets the programmed operator determine if the host has updated the host presentation space or OIA because:

• The Start Host Notification (23) function was called (on first call to the Query Host Update function only)
• The previous call to the Query Host Update function (for all calls to the Query Host Update function except the first).

Prerequisite Calls

Start Host Notification (23)

Call Parameters

The calling data string can contain:

Return Parameters

Notes on Using This Function

The target presentation space must be specified in the data string, even though a connection to the host presentation space is not necessary to check for updates.

Query Session Status (22)

The Query Session Status function is used to obtain session-specific information.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

Return Parameters

This function returns a data string and a return code.

Return Code:

The following codes are defined:

Notes on Using This Function

1. To use this function, preallocate memory to receive the returned data string parameter. The statements required to preallocate this memory vary depending on the language in which your application is written. See Memory Allocation for more information.

Query Sessions (10)

The Query Sessions function returns a 16-byte (12-byte for standard interface) data string describing each host session.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

Return Parameters

This function returns a data string, a length, and a return code.

Data String:

The returned data string is 16n bytes long (12n for standard interface), where n is the number of host sessions. The descriptors are concatenated into the data string and each session type, and presentation space size of a host session.

The format of each 16-byte (12-byte for standard interface) session descriptor is as follows:

Length:

The number of host sessions started.

Return Code:

The following codes are defined:

Notes on Using This Function

1. If an application program receives RC=2 or RC=0, the number of the active sessions is returned in the length field. The application program can recognize the minimum string length by this number.
2. The Query Sessions function is affected by the CFGSIZE/NOCFGZISE session option (see item 16 for more information) and by the EXTEND_PS/NOEXTEND_PS option (see item 22 for more information).

Query System (20)

The Query System function can be used by an EHLLAPI application program to determine the level of Personal Communications support and other system-related values. This function returns a string that contains the appropriate system data. Most of this information is for use by a service coordinator when you call the IBM Support Center after receiving a return code 9 (a system error was encountered).

The bytes in this returned string are defined in Return Parameters.

Prerequisite Calls

There are no prerequisite calls for this function.

Call Parameters

Return Parameters

This function returns a data string and a return code.

Data String:

A data string of 35 bytes (for 16-bit) or 36 bytes (for 32-bit) is returned. The bytes are defined as follows:

Return Code

The following codes are defined:

Notes on Using This Function

To use this function, preallocate memory to receive the returned data string parameter. See Memory Allocation for more information.

Query Window Coordinates (103)

The Query Window Coordinates function requests the coordinates for the window of a presentation space. The window coordinates are returned in pels.

Prerequisite Calls

Connect Window Services (101)

Call Parameters

The calling data string can contain:

Return Parameters

This function returns a data string and a return code.

Return Code:

The following codes are defined:

Read Structured Fields (126)

The Read Structured Fields function allows an application to read structured field data from the host application. If the call specifies S (for Synchronous), the application does not receive control until the Read Structured Fields is completed. If the call specifies A (for Asynchronous), the application receives control immediately after the call. If the call specifies M (for Asynchronous, message mode), the application receives control immediately after the call. The application can wait for the message. In any case (S, A, or M), the application provides the buffer address in which the data from the host is to be placed.

For a successful asynchronous completion of this function, the following statements apply:

The return code field in the parameter list might not contain the results of the requested I/O. If the return code is not 0, the request failed. The application must take the appropriate action based on the return code.

If the return code for this request is 0, the application must use the request ID returned with this function call to issue the Get Request Completion function call to determine the completion results of the function associated with the request ID. The Get Request Completion function call returns the following information:

1. Function request ID
2. Address of the data string from the asynchronous request
3. Length of the data string
4. Return code of the completed function

Prerequisite Calls

Connect for Structured Fields (120) and Allocate Communication Buffer (123)

Call Parameters

The calling data string can contain:

Return Parameters

This function returns a data string and a return code.

Data String:

If A (asynchronous) is specified in position 5, (2 for standard interface) and the function is completed successfully, the following data string is returned:

Data String:

If "M" (asynchronous message mode) is specified in position 5 (2 for 16-bit applications) and the function is completed successfully, the following data string is returned:

Return Code:

The following codes are defined:

Notes on Using This Function

1. Return code 35 will be returned when the first Read Structured Fields or Write Structured Fields is requested after an outbound transmission from the host is canceled. Corrective action is the responsibility of the application.
2. Return code 36 requires that the application disconnect from the emulation program and then reconnect to reestablish communication with the host. Corrective action is the responsibility of the application.
3. Return code 37 will be returned if the host is inbound disabled. The Read Structured Fields function was successfully requested.
4. The EHLLAPI allows for a maximum of 20 asynchronous requests per application to be outstanding. A return code for unavailable resources (RC=11) is returned if more than 20 asynchronous requests are attempted.
5. If you are using an IBM Global Network connection, the maximum number of asynchronous requests is 10.

The structured field data contains the application structured fields received from the host. Structured field headers are removed by the EHLLAPI before the structured field data reaches the application.

The structured field data format is as follows: