[ Previous | Next | Contents | Search ]
3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference

SET SESSION PARAMETERS (9)

Purpose

Enables you to change certain default session options in HLLAPI.

Prerequisite Calls

This function requires no prerequisite calls to other functions.

Syntax

hllc (func, apistring, len, ret)
int *func;
char *apistring;
int *len;
int *ret;

Supplied Parameters

Supply the following parameters to invoke the SET SESSION PARAMETERS function:

func Specifies the number of the function called; must be a 9 for the SET SESSION PARAMETERS function.
apistring Specifies the attributes of the data string; string must contain the values of the session options that are changed. The data string parameter can contain any of the values in the session options. The values should be placed on the data string parameter line, separated by commas or blanks. The sets of parameters are explained in terms of the functions they affect.
len Specifies the exact length of the source data string (the STREOT option is not allowed).
ret Does not apply for this function.

Returned Parameters

len If nonvalid session options were found in the input data string, the len parameter returns the number of valid session parameters that were set. The len parameter remains unchanged if no nonvalid session options were found in the input data string.
ret The following codes are valid:
0 The session parameters were set.
2 One or more parameters were invalid.
9 A system error occurred.

Session Options

The following session options are represented below. The default session options are the first value.

Option 1 The following values determine how the data string length is defined for functions:
Option 2 The following values specifies the character to be used as the EOT delimiter in (source) data strings for HLLAPI 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)
  • RECEIVE FILE (91)
    Value Explanation
    EOT=c This value allows you to specify the EOT character for string terminators (in STREOT mode). Binary 0 is the default. Do not leave a blank before and after the equal sign.

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

Option 3 The following values affect the search functions SEARCH FIELD (30) and SEARCH PRESENTATION SPACE (6).
Value Explanation
SRCHALL The SEARCH FIELD (30) function and the SEARCH PRESENTATION SPACE (6) function scan the entire host PS or field.
SRCHFROM The SEARCH FIELD (30) function and the SEARCH PRESENTATION SPACE (6) function start from a specified PS position (for SRCHFRWD) or end at a specified PS position (for SRCHBKWD).
Option 4 The following values affect the search functions SEARCH FIELD (30) and SEARCH PRESENTATION SPACE (6). They determine in which direction searches are performed.
Value Explanation
SRCHFRWD The SEARCH FIELD (30) function and the SEARCH PRESENTATION SPACE (6) function perform in an ascending direction.
SRCHBKWD The SEARCH FIELD (30) function and the SEARCH PRESENTATION SPACE (6) function perform in a descending direction. A search is satisfied if the first character of the target string is located within the bounds specified for the search.
Option 5 The following values 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 Converts all unknown values to blanks.
ATTRB Passes back all codes that do not have an ASCII equivalent as their original value.
Option 6 The following values affect the PAUSE (18) function.
Value Explanation
FPAUSE Full-duration pause. A pause is instituted for the length of time 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.
Option 7 The following values determine whether HLLAPI automatically precedes strings sent using the SEND KEY (3) function with a reset.
Note: Use the NORESET option to increase the performance of this function.
Value Explanation
AUTORESET HLLAPI 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.
Option 8 The following values affect the WAIT (4) function and the GET KEY (51) function.
Value Explanation
TWAIT The WAIT (4) function waits up to a minute before timing out on XCLOCK or XSYSTEM for the 3270 terminal emulator or on the input-inhibited indicator for 5250 workstation feature. The GET KEY (51) function waits until a keystroke is enqueued before returning.
LWAIT The WAIT (4) function waits until XCLOCK or XSYSTEM clears for the 3270 terminal emulator or until the input-inhibited indicator clears for 5250 workstation feature. This option is not recommended since control does not return to your application until the host is available. The GET KEY (51) function waits until a keystroke has been enqueued before returning.
NWAIT The WAIT (4) function and the GET KEY (51) function checks the status and returns immediately (no wait).
Option 9 The following values affect the following copy functions:
  • 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)
    Value Explanation
    EAB Pass the presentation space data with EABs. (You receive two characters for every one that is displayed. You must allocate a buffer twice the size of the presentation space; for example, 2 x 1920 for a Model 2 screen).
    NOEAB Pass data only (no EABs).
Option 10 The following values affect the format of the Operator Information Area (OIA) image returned by the COPY OIA (13) function.
Value Explanation
OLDOIA Returns the session's OIA in 3270 PC format. For more information, see COPY OIA (13) function.
NEWOIA Does not apply for this function.
Option 11 The following values 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 certain timeout period occurs, or if the function returns immediately after determining if the keyboard is blocked or in use.
Value Explanation
RETRY Continues to attempt to send keystrokes until they are sent, or until a certain timeout period expired.
NORETRY Returns immediately after determining the keyboard is blocked or in use.
Option 12 The following values enable or disable the trace option of HLLAPI. You can use these values to debug an HLLAPI program. The TRON option determines whether the execution of a specified function is traced.
Value Explanation
TROFF Turns trace off.
TRON Turns trace on. When TRON is in effect, all executed HLLAPI functions are traced. The trace output data is in the HCONHLLAPI.TRACE file in the current subdirectory.
Option 13 The following values affect copy_from_host functions:
  • COPY PRESENTATION SPACE (5)
  • COPY PRESENTATION SPACE TO STRING (8)
  • COPY FIELD TO STRING (34)
    Value Explanation
    XLATE Does not apply for this function.
    NO XLATE EABs are not translated.
Option 14 The value of the NULLTOBLANK option affects the following functions:
  • COPY PRESENTATION SPACE (5)
  • COPY PRESENTATION SPACE TO STRING (8)
    Value Explanation
    NULLOK Do not translate NULLs in the Presentation Space to blanks. This is the default value.
    NULLTOBLANK When NULLTOBLANK is in affect, all NULLs in the Presentation Space are converted to spaces when these functions are called.

Additional DBCS Session Options

Option 15 The following values affect the following copy functions:
  • 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)
    Value Explanation
    EAD Pass the presentation space data with two attribute characters about DBCS. (You receive three characters for every one that is displayed. You must allocate a buffer three times the size of the presentation space, for example, 3 x 1920 for a Model 2 screen.)
    NOEAD Pass data only (no EADs).
Option 16 The following values affect the following copy functions:
  • COPY PRESENTATION SPACE (5)
  • COPY PRESENTATION SPACE TO STRING (8)
  • COPY FIELD TO STRING (34)
    Value Explanation
    SPACESO Both shift-out (SO) and shift-in (SI) control characters are converted to space(X'20'). The size of an allocated buffer must be enough to store these characters.
    SO Each shift-out(SO) and shift-in(SI) control character is converted to x'0E' and X'0F'. The size of an allocated buffer must be enough to store these characters.
    NOSO Shift-out (SO) and shift-in (SI) control characters are eliminated from the presentation space data.

Remarks

The SET SESSION PARAMETERS function enables you to change certain default session options. When HLLAPI is loaded, the default values for session options are in effect. Some or all of these values can be changed using the data string parameter. Specified values remain in effect until one of the following occurs:

Related Information

CONNECT PRESENTATION SPACE (1) function and RESERVE (11) function.

[ Previous | Next | Contents | Search ]