Read Data from Session (QsnReadSsnDta) API

The Read Data from Session (QsnReadSsnDta) API is used to read data from a session. A QsnReadInp operation is implicitly performed to read any field data. If the session has a DSM-defined input line, an implicit Clear Field Table (QsnClrFldTbl) operation is issued prior to redefining the session input line on each input operation. The data returned consists of only the data entered. That is, only the data from the cursor position within the field up to the last nonblank input character when an AID generating key is pressed is returned. If the session does not have a DSM- defined input line, data is read from any input fields defined on the screen, and all data, including blanks, is returned. In other respects, the processing of these user-defined input fields will be equivalent with the processing of the DSM-defined input line.

If the previous input operation was a call to QsnReadSsnDtaCC, the session input line will be changed to support the data read by this API.

If an AID key is pressed for which a corresponding function has been defined, this function will be called. Depending upon the return action specified, control would then return to the caller or another input operation will occur. See Command Key Action Routines for details.

Restrictions

If the device supports CCSID-based I/O and the session was not defined with an input line and the application defines input fields on the screen, DSM is not able to determine if the fields are CCSID-capable or which CCSID they support. Since CCSID-based data requires special datastream commands, DSM could send invalid data to the device, or otherwise corrupt or misinterpret the input data. Because of this, the data read from any application defined input fields on the screen will not be echoed to the scroller. Also, the default command key exit routines will not use this data.

Authorities and Locks

None

Required Parameter Group

Session handle

INPUT; BINARY(4)

A handle for the session from which to read input. The session being read from must be the current window. You can use the Set Current Window (QsnSetCurWin) API to change the current window.

Input buffer handle

INPUT; BINARY(4)

A handle for the input buffer to receive the result of the input operations if a direct operation is specified. The input buffer must have been created with the Create Input Buffer (QsnCrtInpBuf) API. The format of the data returned is the same as that of the Read Input Fields (QsnReadInp) API.

Omissible Parameter Group

Number of bytes read

OUTPUT; BINARY(4)

The number of bytes of data read. On a successful read operation, this value is the same as that returned by the Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) API if passed the input buffer resulting from this operation.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Returned Value

Number of bytes read

OUTPUT; BINARY(4)

This API returns the value for the number of bytes read parameter if the operation was successful, -1 if there was a general failure, or -2 if the invite active flag is on in the associated environment and the read from invited device operation timed out.

Error Messages

For examples of Read Data from Session APIs, see Example: Create Session and Read Data.