|
The Set Session Parameters function lets you change certain default session options in EHLLAPI for all sessions. When EHLLAPI is loaded, the default settings for session options are as indicated by the underscored entries in the tables that appear in Session Options . Any, some, or all of these settings can be changed by including the desired option in the calling data string as explained below. Specified settings remain in effect until:
| • | Changed by a subsequent Set Session Parameters (9) function that specifies a new value. |
| • | The EHLLAPI application program is terminated. |
The following table lists those EHLLAPI functions that are affected by session options. Functions not listed in the table are not affected by any of the session options. Session options that affect each function are indicated by corresponding entries in the "See Items" column. These entries are indexed to the list that follows Call Parameters.
Function Number
|
Function Name
|
See Items
|
1
|
Connect Presentation Space
|
11, 23, 24
|
3
|
Send Key
|
1, 2, 9, 10, 19
|
4
|
Wait
|
12
|
5
|
Copy Presentation Space
|
5, 13, 14, 15, 17, 20, 21, 22
|
6
|
Search Presentation Space
|
1, 2, 3, 4
|
8
|
Copy Presentation Space to String
|
5, 13, 14, 15, 17, 20, 21, 22
|
10
|
Query Sessions
|
16, 22
|
15
|
Copy String to Presentation Space
|
1, 2, 13, 14, 18, 20, 21, 22
|
18
|
Pause
|
6
|
30
|
Search Field
|
1, 2, 3, 4, 22
|
33
|
Copy String to Field
|
1, 2, 13, 14, 18, 20, 21, 22
|
34
|
Copy Field to String
|
5, 13, 14, 17, 20, 21, 22
|
51
|
Get Key
|
9, 12
|
90
|
Send File
|
1, 2, 7, 8
|
91
|
Receive File
|
1, 2, 7, 8
|
101
|
Connect Window Services
|
23, 24
|
Note: Items 20 and 21 in this table are for DBCS only
Prerequisite Calls
There are no prerequisite calls for this function.
Call Parameters
|
Standard Interface
|
Enhanced Interface
|
Function Number
|
Must be 9.
|
|
Data String
|
String containing the desired values of those session options that are to be changed. The data string can contain any of the values in the tables of Session Options. The values should be placed on the data string line, separated by commas or blanks. The sets of parameters are explained in terms of the functions they affect.
|
|
Length
|
Explicit length of the source data string (the STREOT option is not allowed).
|
|
PS Position
|
NA.
|
|
Session Options
The following tables show the session options. The default is underlined.
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.
|
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.
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.
|
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.
|
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 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 an Arabic number 0-9 or 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 the application 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.
|
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.
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.
Value
|
Explanation
|
NOXLATE
|
EABs are not translated.
|
XLATE
|
EABs are translated to the PC color graphics adapter (CGA) format.
|
Value
|
Explanation
|
BLANK
|
Convert all unknown values to X'20'.
|
NOBLANK
|
Convert all unknown values to X'00'.
|
| 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.
|
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.
|
Value
|
Explanation
|
NOPUTEAB
|
EAB (or EAD for DBCS) 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.
|
| 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.
|
Value
|
Explanation
|
NOEAD
|
DBCS attribute characters are not passed.
|
EAD
|
Pass the presentation space data and two attribute characters for the double-byte character set (DBCS). (Users receive 2 bytes for each character other than the data. Therefore, a buffer twice the size of the presentation space must be preallocated.)
|
Value
|
Explanation
|
NOSO
|
Pass the presentation space data except Shift-in (SI) and Shift-out (SO) control characters.
|
SO
|
Pass the presentation space data including translated SI control character to X'0E' and SO control character to X'0F'. The allocated buffer size depends on the length of the stored data.
|
SPACESO
|
Pass the presentation space data including translated SI and SO control characters to X'20' (blank). The allocated buffer size depends on the length of the stored data.
|
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.
|
NOEXTEND_PS
|
The presentation space is not extended when the above condition occurs. This is the default value.
|
| 23. | 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.
|
| 24. | 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.
|
Return Parameters
This function returns a length and a return code.
Length
Number of valid session parameters that are set.
Return Code
The following codes are defined:
Return Code
|
Explanation
|
0
|
The session parameters have been set.
|
2
|
One or more parameters were not valid.
|
9
|
A system error was encountered.
|
|