Set Session Parameters

Set Session Parameters – Function 9

This function sets the options of the Host session. Session options that are not set with this function use their default values.

Session options set with this function remain in effect until one of the following occurs:

•

Another Set Session Parameters call sets a new value

•

Reset System (function 21) is called

Prerequisite functions

Connect Presentation Space (function 1)

Function call

WinHLLAPI(SETSESSIONPARAMETERS,lpbyString,lpwLength,lpwReturnnCode)

Call parameters

Parameter	Description
Data String	String containing the desired session options to set. If more than one session option is set, use a comma or space to separate the session options. See “Remarks” section for an explanation of the session options.
Data Length	Explicit length of Data String (EOT cannot be used).
PS Position	NA

Return parameters

Parameter	Description
Data Length	Remains the same as the call value if all session options in Data String are valid. If Data String contains any invalid session options, Data Length is set to the number of valid session options contained in Data String.

Return code

Code	Description
WHLLOK	All of the requested session options set as specified.
WHLLPARAMETERERROR	Your Windows HLLAPI application is currently not connected to a session.Data String contains one or more invalid session options.
WHLLSYSERROR	The function failed due to a system error.

Remarks

The following table lists the functions that are affected by session options, and the session options that affect them.

Function name (function number)	Session options
Connect Presentation Space (function 1)	CONLOG/CONPHYS, WRITE_SUPER/WRITE_WRITE /WRITE_READ/WRITE_NONE /SUPER_WRITE/READ_WRITE, NOKEY/KEY$nnnnnnn
Send Key (function 3)	STRLEN/STREOT, EOT=c, ESC=c, AUTORESET/NORESET, RETRY/NORETRY
Wait (function 4)	TWAIT/LWAIT/NWAIT
Copy Presentation Space (function 5)	NOATTRB/ATTRB, EAB/NOEAB, XLATE/NOXLATE, DISPLAY/NODISPLAY
Search Presentation Space (function 6)	STRLEN/STREOT, EOT=c, SRCHALL/SRCHFROM, SRCHFRWD/SRCHBKWD
Copy Presentation Space to String (function 8)	NOATTRB/ATTRB, EAB/NOEAB, XLATE/NOXLATE, DISPLAY/NODISPLAY
Query Sessions (function 10)	NOCFGSIZE/CFGSIZE
Copy OIA (function 13)	OLDOIA/NEWOIA
Copy String to Presentation Space (function 15)	STRLEN/STREOT, EOT=c, EAB/NOEAB
Pause (function 18)	FPAUSE/IPAUSE
Search Field (function 30)	STRLEN/STREOT, EOT=c, SRCHALL/SRCHFROM, SRCHFRWD/SRCHBKWD
Copy String to Field (function 33)	STRLEN/STREOT, EOT=c, EAB/NOEAB
Copy Field to String (function 34)	NOATTRB/ATTRB, EAB/NOEAB, XLATE/NOXLATE, DISPLAY/NODISPLAY
Get Key (function 51)	ESC=c, TWAIT/LWAIT/NWAIT
Send File (function 90)	STRLEN/STREOT, EOT=c, NOQUIET/QUIET, TIMEOUT=0/TIMEOUT=c
Receive File (function 91)	STRLEN/STREOT, EOT=c, NOQUIET/QUIET, TIMEOUT=0/TIMEOUT=c
Connect PM Window Service (function 101)	WRITE_SUPER/WRITE_WRITE /WRITE_READ/WRITE_NONE /SUPER_WRITE/READ_WRITE

The session options are described on the following pages, grouped by function. Each group of session options lists their general function, which Windows HLLAPI functions they affect, and the characteristics of each session option setting.

STRLEN/STREOT

Specify how the length of Data String is determined. Applies to 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).

Session option	Description
STRLEN	Data Length explicitly defined. This is the default setting.
STREOT	Data Length not necessarily defined; Data String parameter on a function call ends in an EOT character.

EOT=c

When the STREOT session option is set, specify the delimiter character to mark the end of the Data String parameter on a function call. Applies to 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).

Session option	Description
EOT=c	Set the EOT character to “c,” which must be a 1-byte literal character. There must not be a space on either side of the equal sign (“space” is not a valid EOT character). The default EOT character is binary zero.

SRCHALL/SRCHFROM

Determine how the Host session presentation space is to be searched. Applies to Search Presentation Space (6) and Search Field (30).

Session option	Description
SRCHALL	If using Search Presentation Space (6), search the entire Host session presentation space. If using Search Field (30), search the entire field. SRCHALL is the default setting.
SRCHFROM	When session option SRCHFROM is set, start search at the end (of the field or Host session presentation space) and stop at specified PS Position.

SRCHFRWD/SRCHBKWD

When the SRCHFROM session option is set, determine the direction of the search. Applies to Search Presentation Space (6) and Search Field (30).

Session option	Description
SRCHFRWD	If session option SRCHFRWD is set, start search at specified PS Position and stop at the end (of the field or Host session presentation space).
SRCHBKWD	If session option SRCHBKWD is set, start search at the end and stop at specified PS Position.

NOATTRB/ATTRB

Determine how to translate attributes to your Windows HLLAPI application. Applies to Copy Presentation Space (5), Copy Presentation Space to String (8) and Copy Field to String (34).

Session option	Description
NOATTRB	Translate EBCDIC bytes that do not have ASCII equivalents to spaces (ASCII 20h). NOATTRB is the default setting.
ATTRB	EBCDIC bytes that do not have ASCII equivalents are not translated, but are passed as their original EBCDIC values.

FPAUSE/IPAUSE

Determine the type of pause to use. Applies to Pause (18).

Session option	Description
FPAUSE	SEND and RECEIVE messages are displayed.
QUIET	SEND and RECEIVE messages are not displayed.

TIMEOUT=0/TIMEOUT=c

Set the timeout interval to be used during file transfer operations. If a timeout occurs, the file transfer aborts. These options are not supported for 5250 emulation.

Session option	Description
TIMEOUT=0	Set the timeout to 30 seconds. There must not be a space on either side of the equal sign; the value is a zero. TIMEOUT=0 is the default setting.
TIMEOUT=c	Set the timeout to a specific period. A CTRL+BREAK is issued automatically after the specified period. There must not be a space on either side of the equal sign; c is a one-byte character that can be only one of the following values: 1 30 seconds (0.5 minutes) 2 60 seconds (1.0 minutes) 3 90 seconds (1.5 minutes) 4 120 seconds (2.0 minutes) 5 150 seconds (2.5 minutes) 6 180 seconds (3.0 minutes) 7 210 seconds (3.5 minutes) 8 240 seconds (4.0 minutes) 9 270 seconds (4.5 minutes) J 300 seconds (5.0 minutes) K 330 seconds (5.5 minutes) L 360 seconds (6.0 minutes) M 390 seconds (6.5 minutes) N 420 seconds (7.0 minutes)

Session option

Description

TIMEOUT=0

Set the timeout to 30 seconds. There must not be a space on either side of the equal sign; the value is a zero. TIMEOUT=0 is the default setting.

TIMEOUT=c

Set the timeout to a specific period. A CTRL+BREAK is issued automatically after the specified period. There must not be a space on either side of the equal sign; c is a one-byte character that can be only one of the following values:

1 30 seconds (0.5 minutes)
2 60 seconds (1.0 minutes)
3 90 seconds (1.5 minutes)
4 120 seconds (2.0 minutes)
5 150 seconds (2.5 minutes)
6 180 seconds (3.0 minutes)
7 210 seconds (3.5 minutes)
8 240 seconds (4.0 minutes)
9 270 seconds (4.5 minutes)
J 300 seconds (5.0 minutes)
K 330 seconds (5.5 minutes)
L 360 seconds (6.0 minutes)
M 390 seconds (6.5 minutes)
N 420 seconds (7.0 minutes)

ESC=c

Specify the escape character to use for 3270 function key codes. Applies to Send Key (3) and Get Key (51).

Set the escape character to use for 3270 function key codes to c which is a one-byte literal character. There must not be a space on either side of the equal sign (“space” is not a valid escape character). The default escape character is the at sign (@).

AUTORESET/NORESET

Determine if Send Key (function 3) sends a reset prior to the keystroke string or not.

Session option	Description
AUTORESET	A reset precedes the keystroke string specified with a Send Key (3), attempting to reset any states that can be reset (except input-inhibited). AUTORESET is the default setting.
NORESET	A reset does not precede the keystroke string specified with a Send Key (3).

TWAIT/LWAIT/NWAIT

Determine the characteristics of a wait period. Applies to Wait (4) and Get Key(51).

Session option	Description
TWAIT	For Wait (4), wait up to 60 seconds before timing out on XCLOCK or XSYSTEM. For Get Key (function 51), wait until a keystroke is queued before returning. TWAIT is the default setting.
LWAIT	For Wait (4), wait until the XCLOCK or XSYSTEM clears. This setting is not recommended because your Windows HLLAPI does not regain control until the Host is available. For Get Key (51), wait until a keystroke is queued before returning.
NWAIT	No wait period applies. Wait (4) and Get Key (51) calls each check their respective status and return immediately.

TRON/TROFF

Determine whether to enable or disable Windows HLLAPI tracing. The information in the trace is intended to help debug a Windows HLLAPI program. Tracing is turned off when the Windows HLLAPI program ends or when TROFF is specified.

Session option	Description
EAB	Include extended attributes (EABs) with Data String. Since there is an EAB for every character that displays, you must define Data String to be twice the size of the Host session presentation space or field.
NOEAB	Do not include any extended attributes (EABs) with Data String (no EABs). This is the default setting.

XLATE/NOXLATE

Determine the translation of extended attributes (EABs). Applies to Copy Presentation Space (5), Copy Presentation Space to String (8) and Copy Field to String (34).

Session option	Description
XLATE	Translate extended attributes (EABs) into CGA colors.
NOXLATE	Do not translate extended attributes (EABs).

CONLOG/CONPHYS

Specify which application will be the foreground application when connecting to a session. Applies to Connect Presentation Space (1).

Session option	Description
CONLOG	After connection, your Windows HLLAPI application remains the foreground application. CONLOG is the default setting.
CONPHYS	After connection, the specified session becomes the foreground application, updating the session and accepting keyboard input. Your Windows HLLAPI application can still access the session (to monitor for a specific event, for example). To return foreground control to your Windows HLLAPI application, call Disconnect Presentation Space (2).

OLDOIA/NEWOIA

Specify the format for the data returned from Copy OIA (13).

Session option	Description
OLDOIA	Data returned in 3270 PC format. For 5250 support the OIA is always returned in ASCII therefore OLDOIA is accepted but ignored.
NEWOIA	Returns the configured size of the presentation space thereby ignoring any override of the presentation space by the host.

DISPLAY/NODISPLAY

Specify whether nondisplay fields will be copied using Copy Presentation Space (5), Copy Presentation Space to String (8), Copy OIA (13), Copy String to Presentation Space (15), Copy String to Field (33), and Copy Field to String (34).

Session option	Description
DISPLAY	Nondisplay fields are copied to the target buffer in the same manner as display fields.
NODISPLAY	Nondisplay fields are copied as a string of nulls to the target buffer. This allows applications to display the copied buffer in the presentation window without displaying confidential information, such as passwords.

WRITE_SUPER/WRITE_WRITE/WRITE_READ/WRITE_NONE/SUPER_WRITE/READ_WRITE

Specify whether a Windows HLLAPI application can or will share the presentation space to which it is connected with another application using Connect Presentation Space (1) and Connect PM Window Services (101).

Session option	Description
WRITE_SUPER	Set by a Windows HLLAPI application that requires write access and allows only supervisory applications to connect to its presentation space.
WRITE_WRITE	Set by a Windows HLLAPI application that requires write access and allows other applications that have predictable behavior to connect to its presentation space.
WRITE_READ	Set by a Windows HLLAPI application that requires write access and allows other applications to use read-only functions on its connected presentation space.
WRITE_NONE	Set by a Windows HLLAPI application that requires exclusive access to the connected presentation space. No other applications, not even supervisory, will have access to its presentation space.
SUPER_WRITE	Set by a Windows HLLAPI supervisory application allowing applications with write access to share the connected presentation space. The application setting this parameter will not cause errors for other application but provide only supervisory-type functions.
READ_WRITE	Set by a Windows HLLAPI application that requires read-only access and allows other applications that perform read-only functions to connect to its presentation space.

NOKEY/KEY$nnnnnnnn

Allow applications that have sharing requirements to limit access to a partner application (i.e. an application developed to work with it).

Session option	Description
NOKEY	Allows the application to be compatible with existing applications that do not specify the KEY parameter.
KEY$nnnnnnn	Specify the keyword to restrict sharing of the presentation space. The keyword must be exactly 8-bytes long.