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 Refer to items 5, 13, 14, 15, 17, 20, and 21 for more information.

    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.
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 displays 25th row information on row 24, or on the status bar. For information to be displayed on the status bar, the status bar must be configured. Refer to Quick Beginnings for information on configuring the status bar. 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.