Session Options

The following tables show the session options. The default is underlined.
  1. The values in the following table determine how the data string length is defined for functions Send Key (3), Search Presentation Space (6), Copy String to Presentation Space (15), Search Field (30), Copy String to Field (33), Send File (90), and Receive File (91).
    Value Explanation
    STRLEN An explicit length is passed for all strings.
    STREOT Lengths are not explicitly coded. Calling (source) data strings are terminated with an EOT character.

  2. The statement in the following table is used to specify the character that is used as the end-of-text (EOT) delimiter in the calling (source) data string for EHLLAPI functions Send Key (3), Search Presentation Space (6), Copy String to Presentation Space (15), Search Field (30), Copy String to Field (33), Send File (90), and Receive File (91).
    Value Explanation
    EOT=c Allows you to specify the EOT character for string terminators (in STREOT mode). Binary zero is the default. Do not leave a blank after the equal sign.

    To be valid, c must be entered as a 1-byte string literal character with no preceding blanks. The EOT character specified by this statement is used to determine the length of a calling data string only when the STREOT option (see item 1) is in effect.

  3. The values in the following table affect the Search Presentation Space (6) and Search Field (30) search functions.
    Value Explanation
    SRCHALL The Search Presentation Space (6) function and Search Field (30) function scan the entire host presentation space or field.
    SRCHFROM The Search Presentation Space (6) function and Search Field (30) function start from a specified PS position (for SRCHFRWD) or end at a specified PS position (for SRCHBKWD).

  4. The values in the following table affect the Search Presentation Space (6) and Search Field (30) search functions. They determine the direction for the search.
    Value Explanation
    SRCHFRWD The Search Presentation Space (6) function and Search Field (30) function perform in an ascending direction.
    SRCHBKWD The Search Presentation Space (6) function and Search Field (30) function perform in a descending direction. A search is satisfied if the first character of the requested string starts within the bounds specified for the search.

  5. The values in the following table determine how attribute bytes are treated for functions Copy Presentation Space (5), Copy Presentation Space to String (8), and Copy Field to String (34).
    Value Explanation
    NOATTRB Convert all unknown values to blanks.
    ATTRB Pass back all codes that do not have an ASCII equivalent as their original values.
    NULLATTRB Convert all field attributes to null characters.

  6. The values in the following table affect the Pause (18) function.
    Value Explanation
    FPAUSE A full-duration pause lasts for however long you specified in the Pause (18) function.
    IPAUSE Interruptible pause. After the Start Host Notification (23) function is executed, a host event satisfies a pause.

  7. The values in the following table determine whether messages generated by file transfer functions Send File (90) and Receive File (91) are displayed.
    Value Explanation
    NOQUIET SEND and RECEIVE messages are displayed.
    QUIET SEND and RECEIVE messages are not displayed.

  8. The statements in the following table determine how long Z and I Emulator for Windows EHLLAPI waits before it automatically issues a Cancel during execution of file transfer functions Send File (90) and Receive File (91). To be valid, c must be a capital letter J–N and must not be preceded by a blank.
    Value Explanation
    TIMEOUT=0 A Cancel is automatically issued following a 20-second (approximate) delay.
    TIMEOUT=c A Cancel is automatically issued following a specified delay. A 1-character indicator from the table below tells Z and I Emulator for Windows how many 30-second cycles it should accept before issuing a Cancel itself.
    Character
    Value (in minutes)
    1
    0.5
    2
    1.0
    3
    1.5
    4
    2.0
    5
    2.5
    6
    3.0
    7
    3.5
    8
    4.0
    9
    4.5
    J
    5.0
    K
    5.5
    L
    6.0
    M
    6.5
    N
    7.0

  9. The statement in the following table is used to define the escape character for keystroke mnemonics. This session option affects functions Send Key (3) and Get Key (51). The value of c must be entered as a 1-byte literal character string with no preceding blanks.
    Value Explanation
    ESC=c Specifies the escape character for keystroke mnemonics (@ is the default). Do not leave a blank after the equal sign. A blank is not a valid escape character.

  10. The values in the following table determine whether EHLLAPI automatically precedes strings sent using the Send Key (3) function with a reset.
    Value Explanation
    AUTORESET EHLLAPI attempts to reset all inhibited conditions by prefixing all strings of keys sent using the Send Key (3) function with a reset.
    NORESET Do not AUTORESET.

  11. The values in the following table affect the manner in which the Connect Presentation Space (1) command function.
    Value Explanation
    CONLOG Establishes a logical connection between the workstation session and a host session. During Connect, does not jump to the requested presentation space.
    CONPHYS Establishes a physical connection between the workstation session and a host session. During Connect, jumps to the requested presentation space.

  12. The values in the following table affect the Wait (4) function and Get Key (51) function. For each value, there are two different effects, one for each function.
    Value Explanation
    TWAIT For the Wait (4) function, waits up to a minute before timing out on XCLOCK (X []) or XSYSTEM.

    For the Get Key (51) function, does not return control to your EHLLAPI application program until it has intercepted a key (normal or AID key based on the option specified under the Start Keystroke Intercept (50) function).

    LWAIT For the Wait (4) function, waits until XCLOCK (X [])/XSYSTEM clears. This option is not recommended, because control does not return to your application until the host is available.

    For the Get Key (51) function, does not return control to your EHLLAPI application program until it has intercepted a key (normal or AID key based on the option specified under the Start Keystroke Intercept (50) function).

    NWAIT For the Wait (4) function, checks status and returns immediately (no wait).

    For the Get Key (51) function, returns return code 25 (keystrokes not available) in the fourth parameter if nothing is queued matching the option specified under the Start Keystroke Intercept (50) function.

    Note: Use of NWAIT is recommended.
  13. The values in the following table affect Copy Presentation Space (5), Copy Presentation Space to String (8), Copy String to Presentation Space (15), Copy String to Field (33), and Copy Field to String (34). Extended attribute bytes (EAB) include extended character attributes and extended field attributes.
    Value Explanation
    NOEAB Pass data only, no EABs.
    EAB Pass the presentation space data with extended attribute bytes. For each character that appears on the screen, 2 bytes of data are passed. Therefore, a buffer twice the size of the presentation space must be preallocated; for example 2 x 1920 = 3840 for a 24-row by 80-column presentation space.

    Extended attributes for a string of characters may be reported as attributes of the field byte, rather than as attributes of each individual character in the field. In this case, to tell if a particular character or set of characters on a screen is underscored, do a CopyPStoString specifying the position of the field attribute byte (the byte before the field that is displayed on the screen) to get the EAB information that applies to all of the characters in that field.

    Note: When using EHLLAPI Copy PS to String, text is copied which should be invisible to the operator. Use the EHLLAPI Set Session Parameters function to set the NODISPLAY option to determine if there is hidden data. This causes EHLLAPI to return nondisplay fields as nulls. Another common procedure for hiding data is to set the foreground and background colors the same (BLACK, for instance) so the text is displayed, but not visible to the human operator. The only way for your application to detect this is to use the EAB and XLATE session parameters and then copying the PS. The foreground/background color of each position is returned and you can determine which characters are invisible.
  14. The values in the following table affect Copy Presentation Space (5), Copy Presentation Space to String (8), Copy String to Presentation Space (15), Copy String to Field (33), and Copy Field to String (34).
    Value Explanation
    NOXLATE EABs are not translated.
    XLATE EABs are translated to the PC color graphics adapter (CGA) format.

  15. The values in the following table affect Copy Presentation Space (5), Copy Presentation Space to String (8) and Copy Presentation Space to Clipboard (35) if NOATTRB and NOEAB are specified.
    Value Explanation
    BLANK Convert all unknown values to X'20'.
    NOBLANK Convert all unknown values to X'00'.
    The default value is BLANK. If you want to change the default value to NOBLANK, add the following statement in the PCSWIN.INI file located in the Z and I Emulator for Windows user-class application data directory: 
    [API]
NullToBlank=NO
  16. The values in the following table affect the presentation space size that is returned by the Query Sessions (10).
    Value Explanation
    CFGSIZE Returns the configured size of the connected presentation space. This option ignores any override of the configured size by the host.
    NOCFGSIZE Returns the current size of the connected presentation space.

  17. The values in the following table affect Copy Presentation Space (5), Copy Presentation Space to String (8), Copy Field to String (34) and Copy Presentation Space to Clipboard (35).
    Value Explanation
    DISPLAY Copy nondisplay fields in the presentation space to the target buffer area in the same manner as display fields. Current applications function normally.
    NODISPLAY Do not copy nondisplay fields in the presentation space to the target buffer area. Copy the nondisplay fields to the target buffer as a string of null characters. This allows applications to display the copied buffers in the presentation widow without displaying confidential information, such as passwords.

  18. The values in the following table affect Copy String to Presentation Space (15), Copy String to Field (33) and Paste Clipboard to Presentation Space (36).
    Value Explanation
    NOPUTEAB EAB is not contained in the data string of Copy String to Presentation Space or Copy String to Field.
    PUTEAB EAB is contained with character data in the data string of Copy String to Presentation Space or Copy String to Field.

    This option is used for the compatibility with Communication Manager/2. For Communication Manager/2, the data string, which is specified in Copy String to Presentation Space or Copy String to Field, must be contain EAB (or EAD) with character data when EAB (or EAD) is valid in Set Session Parameters. Whereas, for the previous Z and I Emulator for Windows, the data string specified in these functions must consist of character data only even if EAB (or EAD) is valid. But Z and I Emulator for Windows allows that the data string contains EAB (or EAD) by setting PUTEAB to provide the compatibility with Communication Manager/2.

  19. The values in the following table affect the Send Key (3) function. Keystrokes are not processed if the keyboard is blocked or in use. The options determine whether the function tries to resend the keystrokes until a 4-minute timeout occurs or if the function returns immediately after determining the keyboard is blocked or in use.
    Value Explanation
    RETRY Continues to attempt to send keystrokes until they are sent or until a 4-minute timeout occurs.
    NORETRY Returns immediately after determining the keyboard is blocked or in use.

  20. The values in the following table affect Copy Presentation Space (5), Copy Presentation Space to String (8), Copy String to Presentation Space (15), Copy String to Field (33), Copy Field to String (34) Search Field (30), Query Sessions. (10), Copy Presentation Space to Clipboard (35) and Paste Clipboard to Presentation Space (36).
    Value Explanation
    EXTEND_PS 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. Z and I Emulator for Windows displays 25th row information on row 24, but EHLLAPI normally sees the real 24th row. By 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.
    NOEXTEND_PS The presentation space is not extended when the above condition occurs. This is the default value.
  21. The values in the following table affect the Connect Presentation Space (1) and Connect Window Services (101) functions. The options specify whether an application can or will share the presentation space to which it is connected with another application. Only one of the following values can be specified with each Set Session Parameter call.
    Value Explanation
    SUPER_WRITE The application allows other applications that allow sharing and have write access permissions to concurrently connect to the same presentation space. The originating application performs supervisory-type functions but does not create errors for other applications that share the presentation space.
    WRITE_SUPER The application requires write access and allows only supervisory application to concurrently connect to its presentation space. This is the default value.
    WRITE_WRITE The application requires write access and allows partner or other applications with predictable behavior to share the presentation space.
    WRITE_READ The application requires write access and allows other applications that perform read-only functions to share the presentation space. The application is also allowed to copy the presentation space and perform other read-only operations as usual.
    WRITE_NONE The application has exclusive use of the presentation space. No other applications are allowed to share the presentation space, including supervisory applications. The application is allowed to copy the presentation space and perform read-only operations as usual.
    READ_WRITE The application requires only read access to monitor the presentation space and allows other applications that perform read or write, or both, functions to share the presentation space. The application is also allowed to copy the presentation space and perform other read-only operations as usual.

  22. The values in the following table allow applications that have presentation space sharing requirements to limit the sharing to a partner application (an application that was developed to work with it).
    Value Explanation
    NOKEY Allows the application to be compatible with existing applications that do not specify the KEY parameter.
    KEY$nnnnnnnn Uses a keyword to restrict sharing access to the presentation space that it supports. The keyword must be exactly 8 bytes in length.