Using Session Services APIs

Session Details

The following figure shows the default attributes provided by the DSM session description for a session.

Session Attributes

    ... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ... ... 8
  *-------------------------------------------------------------------------------*
 1|                                                                               |
 2|            ....................................                               |
 3|            : *------------------------------* :                               |
 4|            : |                              | :                               |
 5|            : |                              | :                               |
 6|            : |                              | :                               |
 7|            : |          SCROLLER            | :                               |
 8|            : |                              | :                               |
 9|            : |                              | :                               |
10|            : *------------------------------* :                               |
11|            :                                  :                               |
12|            : ===> __________________________  :                               |
13|            : ________________________________ :                               |
14|            :                                  :                               |
15|            : F3=Exit   F6=Print   F9=Retrieve :                               |
16|            : F14=Move F15=Resize F22=Switch   :                               |
17|            :                                  :                               |
18|            :..................................:                               |
19|                                                                               |
20|                                                                               |
21|                                                                               |
22|                                                                               |
23|                                                                               |
24|                                                                               |
  .-------------------------------------------------------------------------------.

The main component of a session is the scrollable area, or scroller, where output data can be displayed for the session. A session may or may not have a data input line, depending on the application. A session that uses the default attributes has an input line underneath the scroller. You can allow the size and location of the session attributes to default based on the window size, or you can specify these explicitly. Up to two lines of command key descriptions can appear below the scroller and can be managed by a session. For details on the session description see Create a Session (QsnCrtSsn) API.

When a window containing a session is moved or resized, the scroller and any automatically defined fields are redrawn to reflect the new window positions and size. If any additional items have been added to the session through the low-level interface APIs, you must supply an exit program that will reposition such items explicitly. See Create a Session (QsnCrtSsn) API for details on the exit program.

Line Mode and Character Mode I/O

Session I/O can be performed in a line mode or a character mode basis. In line mode, each call to the line-specific interfaces operates on a complete line, either on input or output. In character mode, I/O is performed a character at a time. This means that multiple I/O operations can be issued to operate on the current line. For example, an output operation could output several characters. Then a backspace operation could be followed by input from the current cursor position. (All input operations are still performed in block mode, where the input is not available until an AID-generating key has been pressed.)

Line mode output is performed using the Write Line to Scroller (QsnWrtSclLin) API. This API writes a line of data to the next session line and sets the active position (see Active Position) to the start of the next line after the added line. For character output, the Write Characters to Scroller (QsnWrtSclChr) API is used. This API outputs a string of characters starting at the active position. After this operation completes, the active position is one position past the last character written, or it is the position specified by a control character sequence if this appears at the end of the data.

Command Key Action Routines

Part of the session description is an array of command key actions. Each action is an exit routine that is specified as a function pointer. When a command key is pressed during a QsnReadSsnDta operation, if an action has been specified, the appropriate exit routine is called. Otherwise, an Invalid key pressed error message will be issued. DSM provides a group of functions that can be called, or user-defined exit-routines can be specified. The action routines are specified as an array of 24 function pointers in the session description. (See Create a Session (QsnCrtSsn) API for details.) The default values for the action routines DSM calls are:

The default action routines for command keys 7, 8, 19, and 20 (QsnRollSclDown, QsnRollSclUp, QsnShfSclL, and QsnShfSclR, respectively) will pass any numeric input to the API when the command key is pressed. For example, to shift the scroller to the right by 10 columns, the value 10 could be entered at the input line prior to pressing command key 20. Non-numeric input is ignored.

When a user-defined action routine is called, it is passed the following information:

When the specified command key is pressed, the action routine for the command key is called. If you change the default values to have a command key call a different DSM API, you cannot specify the API directly because the action routine is passed specific parameters. You must define an action routine that can accept the action routine parameters and then call the desired DSM API with the appropriate parameters. You can define a generic action routine that is specified for each key you want to define, and in that action routine query the input buffer to determine the command key pressed and the appropriate action to take.

When an action routine is called, any data on the input line will remain. You can use the QsnWTD API to clear the line. However, if you write to the session or perform any action that causes the session to be redrawn in the action routine, the data on the input line will be lost.

If an exception occurs during the processing of an action routine, it is ignored and processing continues. A CPFA3D9 will be issued as an exception from the QsnReadSsnDta API when control returns from the action routine. You can handle exceptions explicitly by adding an exception handler to the action routine.

Action Routine Parameters

Session handle

INPUT; BINARY(4)

The session currently active. If the action routine causes the active session to change, this variable will be changed to reflect the new session.

Input buffer

INPUT; BINARY(4)

The input buffer containing the results of the input operations that caused this exit routine to be called. The input buffer can be queried using the low-level interface routines. This is the buffer that was passed to QsnReadSsnDta.

Returned action

OUTPUT; CHAR(1)

The variable containing the flag indicating if, following a successful return from this exit routine, control returns to the caller of the Read Data from Session (QsnReadSsnDta) API or if QsnReadSsnDta handles the next input operation. If an error occurs in the exit routine, control always returns to the caller. The possible values are:

0	QsnReadSsnDta continues to handle the next input operation. Control does not return to the caller.
1	QsnReadSsnDta returns control to the caller. The output parameters for QsnReadSsnDta are filled in appropriately.

Active Position

The active position in the scroller is the point at which data will be written for character mode operations. The active position is affected by output operations to the scroller, including the writing of data that contains EBCDIC display control character sequences.

DSM does not allow the application to partially overwrite data of one type, with another type of data. Instead, it removes the mismatched data and all data that follows it from the scroller line, so that the new data may be inserted in its place.

A single scroller line can contain a mixture of data types, including EBCDIC, DBCS and CCSID-based data. The QsnSclBS and QsnSclCR APIs change the active position of the scroller line. Subsequent calls to the QsnWrtSclChr or QsnWrtSclChrCC APIs will cause existing data in the line to be overwritten, starting at the active position. If the new data is the same type or CCSID of the existing data, the new data will replace the existing data. However, if the existing data is not the same type or CCSID as the new data, DSM will remove the subset of mismatched existing data from the line. Any data in the line that follows the mismatched data will also be removed.

For example, the scroller line contains some EBCDIC data followed by DBCS data. The QsnSclBS API is called such that the active position is moved within the DBCS data. If QsnWrtSclChr is called to write EBCDIC data to the active position, the DBCS data is removed from the line and the new EBCDIC data is written. The result is a line that contains the original EBCDIC data with the new EBCDIC data appended to it.

Consider the same scroller line that contains EBCDIC followed by DBCS data. QsnSclBS is called such that the active position is before the last byte of EBCDIC data. If QsnWrtSclChr is called to write two bytes of EBCDIC data, the last byte of existing EBCDIC data is replaced. However, the second byte of the new data would overwrite the shift out character of the existing DBCS data. DSM will remove the DBCS data from the line, and write the last byte of the new EBCDIC data to the line. The result is a line that contains all but the last byte of the original EBCDIC data with the new EBCDIC data appended to it.

In both examples, if other combinations of EBCDIC, DBCS or CCSID-based data were present in the line after the DBCS data, all of that data would have also been removed with the DBCS data. If other combinations of data types or CCSIDs in the line would have preceded the EBCDIC data, all of the preceding data would be unchanged.

EBCDIC Display Control Characters

The data written to the scroller may contain display control characters consisting of single byte EBCDIC values. If specified on the session description (see Create a Session (QsnCrtSsn) API), the APIs for writing data to the scroller will check for and interpret such control characters. Each control character recognized in the output data is replaced by a call to a DSM API or internal routine that will perform the appropriate function. The following table shows the control characters that are recognized and the APIs that are called, where applicable.

EBCDIC Display Control Characters

DBCS Considerations

If the low-level environment description (see Format of the Low-Level Environment Description) for the session specifies DBCS support, the session services will check for and handle DBCS data. DBCS data must be enclosed by shift control (SO/SI) characters. The DBCS support field determines the type of the input field defined for the session, but does not affect the checking done for session output data other than to indicate that DBCS data may be present. The scroller does not display data using extended NLS attributes, regardless of the underlying display device support.