| 1 | Session description | Input | Char(*) |
| 2 | Length of session description | Input | Binary(4) |
| 3 | User extension information | Input | Char(*) |
| 4 | Length of user extension information | Input | Binary(4) |
| 5 | Start session flag | Input | Char(1) |
| 6 | Window description | Input | Char(*) |
| 7 | Length of window description | Input | Binary(4) |
| 8 | Low-level environment description | Input | Char(*) |
| 9 | Length of low-level environment description | Input | Binary(4) |
| 10 | Session handle | Output | Binary(4) |
| 11 | Error code | I/O | Char(*) |
| Session handle | Output | Binary(4) |
The Create a Session (QsnCrtSsn) API creates a session and returns a handle for the created session. The session must be deleted using the Delete Low-Level Environment (QsnDltEnv) API.
None.
The defined attributes of the session to be created. It must be declared aligned on a 16-byte boundary. The format of the session description is shown in Format of the Session Description.
The length of the session description parameter.
Information that is used to associate data and exit routines with the session. This parameter is required if the user extension information length parameter is supplied. This essentially enables the object-oriented programming concept of inheritance, allowing the session to be extended in a natural way. The user extension data cannot be changed once the session has been created. The format of this parameter is shown in the section Format of the Session User Extension Data.
The length of the user extension information parameter.
Whether or not the session should be displayed on screen when it is created. The possible values are:
| 0 | Do not display the session on the screen when it is created. If you specify this value, you must use the Start a Window (QsnStrWin) API to display the session. |
| 1 | Display the session on the screen when it is created. This is the default. |
The defined attributes for the window containing the session. This parameter is required if the window description length parameter is supplied. The format of the window description is shown in Format of the Window Description. If this parameter is omitted, a window will be created with default values.
The length of the window description parameter.
operating environment for low-level operations used to create and manipulate the windows. This parameter is required if the low-level environment description length parameter is supplied. The format of the low-level environment description is shown in Format of the Low-Level Environment Description. If this parameter is omitted, a low-level environment will be created with default values.
The length of the low-level environment description parameter.
The variable containing a handle for the created session after the QsnCrtSsn API has completed. This handle can be used across activation groups if the activation group in which the handle was created is still active.
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.
This API returns the value for the session handle parameter or -1 if an error occurs during processing.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | PTR(PP) [24] | Array of command key actions |
| 384 | 180 | BINARY(4) | top row of scroller |
| 388 | 184 | BINARY(4) | left column of scroller |
| 392 | 188 | BINARY(4) | Number of rows in scroller |
| 396 | 18C | BINARY(4) | Number of columns in scroller |
| 400 | 190 | BINARY(4) | Default number of rows to roll scroller by |
| 404 | 194 | BINARY(4) | Default number of columns to shift scroller by |
| 408 | 198 | BINARY(4) | Scroller buffer initial size |
| 412 | 19C | BINARY(4) | Scroller buffer maximum size |
| 416 | 1A0 | BINARY(4) | Scroller buffer increment |
| 420 | 1A4 | BINARY(4) | Number of rows for input line |
| 424 | 1A8 | CHAR(1) | Reserved |
| 425 | 1A9 | CHAR(1) | Wrap indication |
| 426 | 1AA | CHAR(1) | Reserved |
| 427 | 1AB | CHAR(1) | Display control characters indication |
| 428 | 1AC | CHAR(1) | Echo session input |
| 429 | 1AD | CHAR(1) | Show scroller lines |
| 430 | 1AE | CHAR(1) | Show scroller characters |
| 431 | 1AF | CHAR(1) | Show command key descriptions |
| 432 | 1B0 | CHAR(1) | Command key attribute for a monochrome display |
| 433 | 1B1 | CHAR(1) | Command key attribute for a color display |
| 434 | 1B2 | CHAR(1) | Input line attribute for a monochrome display |
| 435 | 1B3 | CHAR(1) | Input line attribute for a color display |
| 436 | 1B4 | BINARY(4) | Offset to input line prompt |
| 440 | 1B8 | BINARY(4) | Length of input line prompt |
| 444 | 1BC | BINARY(4) | Offset to command key description line 1 |
| 448 | 1C0 | BINARY(4) | Length of command key description line 1 |
| 452 | 1C4 | BINARY(4) | Offset to command key description line 2 |
| 456 | 1C8 | BINARY(4) | Length of command key description line 2 |
| 460 | 1CC | CHAR(20) | Reserved. |
| * | * | CHAR(*) | Input line prompt |
| * | * | CHAR(*) | Command key description line 1 |
| * | * | CHAR(*) | Command key description line 2 |
In the following descriptions, the default value refers to the value set by the Initialize Session Description (QsnInzSsnD) API.
Array of command key actions. An array of 24 function pointers, each corresponding to the action to be performed when the associated command key is pressed. An element that is specified as a null pointer indicates that the command key is invalid. An element can also be set to the dummy routine QsnSameAction, in which case the current action routine for that key is used. If a command key action is set to the dummy routine QsnDefaultAction, then the default action for that key is used. The defaults for command key actions and the parameters passed to the action routines are described in Command Key Action Routines. The procedures are exported as part of the service program that contains the DSM session services.
Command key attribute for a color display. The default value is X'28' for red.
Command key attribute for a monochrome display. The default value is X'20' for normal attribute.
Command key description line 1. The text string for the first line of command key descriptions.
Command key description line 2. The text string for the second line of command key descriptions.
Default number of columns to shift scroller by. The default number of columns to shift scroller by for the Shift Scroller left (QsnShfSclL) and Shift Scroller center (QsnShfSclR) APIs. This value must be a positive integer value. If 0 is specified, the default is the number of columns in the scroller less two (two scroller columns are reserved for the prefix area).
Default number of rows to roll scroller by. The default number of rows to roll scroller by for the Roll Scroller Up (QsnRollSclUp) and Roll Scroller Down (QsnRollSclDown) APIs. This value must be a positive integer value. If 0 is specified, the default is the number of rows in the scroller.
Display control characters indication. Specifies whether or not scroller lines contain EBCDIC display control characters. If the data contains such control characters and this is not indicated, unexpected results can occur. (See EBCDIC Display Control Characters for details of the control characters supported and their interpretation.) The possible values are:
| 0 | Scroller lines do not contain EBCDIC display control characters. This is the default when the display device or emulator does not support DBCS data. |
| 1 | Scroller lines contain EBCDIC display control characters. If 1 is specified, any data written to the session with a value below X'40' is converted to blank. This is the default when the display device or emulator supports DBCS data. |
Echo session input. Specifies whether lines entered at the session command line are to be echoed to the scroller. The possible values are:
| 0 | Do not echo session input lines to the scroller. |
| 1 | Echo session input lines to the scroller. This is the default. |
Input line attribute for a color display. The default value is X'24' for green underline attribute. If X'00' is specified, the default value is used.
Input line attribute for a monochrome display. The default value is X'24' for underline attribute. If X'00' is specified, the default value is used.
Input line prompt. The text string for the input line prompt.
Left column of scroller. This position is relative to the left of the window which is column 1. The default is 1.
Length of command key description line 1. This value must not exceed the maximum number of columns in the window. The default value is 0. No space is used in the session for this line. If the description line cannot be displayed completely within the window, it is truncated to fit.
Length of command key description line 2. This value must not exceed the maximum number of columns in the window. The default value is 0. No space is used in the session for this line. If the description cannot be displayed completely in the window, it is truncated to fit.
Length of input line prompt. This value must not exceed the maximum number of columns in the window. A value of 0 specifies that there is no prompt. The default value is -1 and corresponds to the default input line prompt ===.
If the input line cannot be displayed completely within the window, it is truncated to fit. The input line will continue on the next window line.
Number of columns in scroller. This value must be a positive integer no greater than the number of columns in the session window. If 0 is specified, the default is the number of columns remaining in the window from the left column of the scroller. This value includes the 2 bytes used for the prefix area to the left of the scroller input line.
If the low level environment supports DBCS, this value must be greater than or equal to 6 to allow for the size of the prefix area, the shift control (SO/SI) characters and one DBCS character.
If the display device or emulator supports CCSID-based I/O, this value must be greater than or equal to 4 to allow for the size of the prefix area and one UCS2 character.
Number of rows for input line. The input line starts in the row specified by the formula: last window row less the number of rows required for input line less the number of rows required for the function key descriptions. The input line will start one column past the end of the input line prompt. If there is no input line prompt, then the input line starts one byte to the center of the leftmost usable column of the window. If this value is 0, then no input line is created. The default is 1.
Number of rows in scroller. This value must be a positive integer no greater than the number of rows in the session window. If 0 is specified, the default is the number of rows remaining in the window from the top row of the scroller.
Offset to command key description line 1. The offset from the beginning of the structure to the start of the command key description line 1. This field is ignored if the length of command key description line 1 field specifies no command key description. The offset plus the length must be less than the session description length.
Offset to command key description line 2. The offset from the beginning of the structure to the start of the command key description line 2. This field is ignored if the length of command key description line 2 field specifies no command key description. The offset plus the length must be less than the session description length.
Offset to input line prompt. The offset from the beginning of the structure to the start of the input line prompt. This field is ignored if the length of input line prompt field specifies no prompt or the default prompt. The offset plus the length must be less than the session description length.
Reserved. This field must be set to X'00'.
Scroller buffer increment. Specifies, in bytes, the amount to increment the scroller buffer size by when the buffer is full and the buffer-full action is to increment the buffer size. The default value is 2000 bytes.
If the scroller buffer cannot be incremented because of insufficient resources, data at the beginning of the scroller will be removed to create space for the new data.
Scroller buffer initial size. The initial buffer size, in number of bytes, that will be allocated for storing the session scroller lines. The default value is 2000 bytes.
Scroller buffer maximum size. The maximum buffer size, in bytes, that will be allocated for storing the session scroller lines. The default value is 0, indicating no maximum size.
Show command key descriptions. Whether or not the function key description lines are to be shown. The possible values are:
| 0 | Do not show function key descriptions. |
| 1 | Show function key descriptions. This is the default. |
Show scroller characters. Whether or not characters written to the scroller in character mode are shown immediately on the screen. You can use the scroller line and character display options together to specify that groups of characters are not displayed immediately, but each complete line is. The possible values are:
| 0 | Do not show characters on the screen as they are written. Use the Display Scroller bottom (QsnDspSclB) API to display the scroller data on the screen. This is the default. |
| 1 | Show scroller characters on the screen as they are written. |
Show scroller lines. Whether or not lines written to the scroller are shown immediately on the screen. The possible values are:
| 0 | Do not show scroller lines on the screen as they are written. Use the Display Scroller bottom (QsnDspSclB) API to display the scroller lines on the screen. This is the default. |
| 1 | Show scroller lines on the screen as they are written. |
Top row of scroller. This position is relative to the top of the window, which is row 1. The default is 1.
Wrap indication. How to handle lines that do not fit within the session window. Possible values are:
| 0 | Truncate lines that do not fit. The truncated portion of the line may be viewed by scrolling to the center. |
| 1 | Wrap lines to the next line. This is the default. |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | PTR(SPP) | User data associated with the session |
| 16 | 10 | PTR(PP) | Exit routine to call when the session is changed |
| 32 | 20 | PTR(PP) | Exit routine to call when window is deleted |
| 48 | 30 | PTR(PP) | Exit routine to call when window coordinates are changed |
| 64 | 40 | PTR(PP) | Exit routine to call when window is drawn |
| 80 | 50 | PTR(PP) | Exit routine to call when this window made current |
Exit routine to call when session changed. The exit routine to call when a session is changed using the Change Session (QsnChgSsn) API.
Exit routine to call when window coordinates changed. The exit routine to call when the window coordinates are changed using the QsnMovWin, Move Window by User (QsnMovWinUsr), Resize Window ( QsnRszWin), or Resize Window by User (QsnRszWinUsr), APIs.
Exit routine to call when window deleted. The exit routine to call when a window is deleted using the Delete Low-Level Environment (QsnDltEnv) API.
Exit routine to call when window drawn. The exit routine to call when a window is drawn using the Display Window (QsnDspWin) API.
Exit routine to call when window made current. The exit routine to call when this window is made current using the Set Current Window (QsnSetCurWin) API.
User data associated with the session. This is a pointer to any data that the user wants to associate with this session.
Exit routines are user-supplied functions with a defined interface. The routines are called from certain APIs and allow the programmer to attach additional function to those APIs. For instance, if fields have been set up in a window, a Change Coordinates exit routine could be supplied to move the fields if the window is moved.
This exit routine, if specified on the user extension information, is called when the session is changed. The following parameter is passed to the exit routine:
| 1 | Session handle | Input | Binary(4) |
The session that was changed.
This exit routine, if specified on the user extension information, is called when the session is deleted. The following parameter is passed to the exit routine:
| 1 | Session handle | Input | Binary(4) |
The session that was deleted.
This exit routine, if specified on the user extension information, is called when the move or resize APIs are called. It is called after the session has been successfully moved or resized, but before the session is drawn on the screen. For this reason, you should not use this exit routine to draw anything in the session. The draw exit routine will be called when the session is moved or resized. The following parameters are passed to the exit routine:
| 1 | Session handle | Input | Binary(4) |
| 2 | Top border offset | Input | Binary(4) |
| 3 | Left border offset | Input | Binary(4) |
| 4 | Bottom border offset | Input | Binary(4) |
| 5 | Center border offset | Input | Binary(4) |
The Session for which the coordinates were changed.
The offset, in screen rows, from the previous top session border to the current top session border (after the session coordinates have been changed). It can be positive, negative, or zero, depending on how the top session border was changed. For example, if the top border was moved down two rows, this value would be 2; if it was moved up 4 rows, this value would be -4; if the top row was not changed, this value would be 0.
The offset, in screen columns, from the previous left session border to the current left session border (after the session coordinates have been changed). It can be positive, negative, or zero, depending on how the left session border was changed. For example, if the left border was moved two columns to the center, this value would be 2; if it was moved 4 columns to the left, this value would be -4, and if the left column was not changed, this value would be 0.
The offset, in screen rows, from the previous bottom session border to the current bottom session border (after the session coordinates have been changed). It can be positive, negative, or zero, depending on how the bottom session border was changed. For example, if the border was moved down two rows, this value would be 2; if it was moved up 4 rows, this value would be -4; if the bottom row was not changed, this value would be 0.
The offset, in screen columns, from the previous center session border to the current center session border (after the session coordinates have been changed). It can be positive, negative, or zero, depending on how the center session border was changed. For example, if the center border was moved two columns to the center, this value would be 2; if it was moved 4 columns to the left, this value would be -4; if the center column was not changed, this value would be 0.
If an exception occurs during the processing of an exit routine, the exception is ignored and processing continues. A CPFA318 will be issued as a diagnostic message only. You can explicitly handle errors in an exit routine by adding an exception handler to the routine.
This exit routine, if specified on the user extension information, is called when the Display Window (QsnDspWin) API is called, before the session is drawn. Because the exit routine is called before the session is drawn, you should only write inside the session using the command buffer parameter. Direct operations should not be used for the exit routine.
The following parameters are passed to the exit routine:
| 1 | Session handle | Input | Binary(4) |
| 2 | Command buffer | Input | Binary(4) |
The session to be drawn.
The command buffer used to store the commands that re-create the window contents. The contents of the command buffer are written to the screen along with the window border. This allows the window and its contents to be redrawn in a single I/O operation.
This exit routine, if specified on the user extension information, is called when the session is made current through the Set Current Window (QsnSetCurWin) API. The following parameter is passed to the exit routine:
| 1 | Session handle | Input | Binary(4) |
A handle for the session that is made current.
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPFA314 E | Memory allocation error. |
| CPFA318 E | Error calling exit routine. |
| CPFA327 E | Low level environment description value incorrect. |
| CPFA31E E | Required parameter &1 omitted. |
| CPFA343 E | Output operation not done. |
| CPFA344 E | The file &2 in library &3 is not valid. |
| CPFA345 E | The invite active flag is not valid. |
| CPFA3A1 E | Window description value is incorrect. |
| CPFA3AB E | The value for &1 must be '0' or '1'. |
| CPFA3D1 E | Session description value is incorrect. |
Additional errors may be generated by this API. They are listed under the applicable API as follows:
| Error Category (API) | Page Reference |
|---|---|
| Environment description (QsnCrtEnv) | Error Messages |
| Window description (QsnCrtWin) | Error Messages |
For examples of Create Session APIs, see Create Session and Read Data--Example.
[ Back to top | Dynamic Screen Manager APIs | APIs by category ]