Using Session I/O APIs

Performance Considerations

Specifying EBCDIC control-character options on the session description can incur overhead. Additional processing is required to handle these. Specifying the scroller line and character display as immediate can incur additional overhead. An output operation will occur for each line or group of characters written. If you need to write multiple lines to the scroller, you can achieve better performance by delaying line display until all the lines are written. Then you can use the Display Scroller Bottom (QsnDspSclB) API to display the data on the screen.

Create Session and Read Data--Example

The sample program in Figure 1 shows how to create and read data from a session. The resulting screen output is shown in Figure 2.

Figure 1. Program for Creating a Session and Reading Data

#include <stddef.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include "qsnapi.h"

#define TRUE    1
#define FALSE   0

#define PF1 "PF4 - Move   PF5 - Resize"
#define PF2 "PF6 - Print"

typedef struct {
    Qsn_Ssn_Desc_T sess_desc;
    char           buffer[100];
} storage_t;

int main (void)
{
    Qsn_Inp_Buf_T ibuf = 0;
    char *fld_dta;
    int i;
    char text[100];
    storage_t    storage;

    Qsn_Ssn_T       session1;
    Qsn_Ssn_Desc_T  *sess_desc = (Qsn_Ssn_Desc_T *) &storage;
    Qsn_Win_Desc_T  win_desc;
    Q_Bin4          win_desc_length = sizeof(win_desc);
    char           *pf1 = PF1;
    Q_Bin4          pf1_len = sizeof(PF1) - 1;
    char           *pf2 = PF2;
    Q_Bin4          pf2_len = sizeof(PF2) - 1;
    Q_Bin4          sess_desc_length = sizeof(Qsn_Ssn_Desc_T) + pf1_len +
                                       pf2_len;

    /* initialize and set up session and window descriptions */
    QsnInzSsnD( sess_desc, sess_desc_length, NULL);
    QsnInzWinD( &win_desc, win_desc_length, NULL);

    sess_desc->cmd_key_desc_line_1_offset = sizeof(Qsn_Ssn_Desc_T);
    sess_desc->cmd_key_desc_line_1_len = pf1_len;
    memcpy( storage.buffer, pf1, pf1_len );

    sess_desc->cmd_key_desc_line_2_offset = sizeof(Qsn_Ssn_Desc_T) +
                                            pf1_len;
    sess_desc->cmd_key_desc_line_2_len = pf2_len;
    memcpy( storage.buffer + pf1_len, pf2, pf2_len );

    sess_desc->scl_line_dsp  = '1';
    sess_desc->scl_chr_dsp  = '1';
    sess_desc->num_input_line_rows = 2;
    sess_desc->wrap = '0';

    QsnCrtSsn( sess_desc, sess_desc_length, NULL, 0,  '1',
              &win_desc, win_desc_length, NULL, 0,
              &session1, NULL);

    if (ibuf == 0)
        ibuf = QsnCrtInpBuf(100, 50, 0, NULL, NULL);
    while ( TRUE ) {
        QsnReadSsnDta( session1, ibuf, NULL, NULL);
        /* check if any data read, then end if exit entered */
        if ( (fld_dta=QsnRtvFldDta(ibuf, NULL, NULL)) != NULL) {
            if (strncmp(fld_dta, "exit", 4) == 0)
                break;
        }
    }
 }

Figure 2. Screen Output from Create Session Program

+--------------------------------------------------------------------------------+
|  ..............................................................................|
|  : > this is line 1                                                        :|
|  : > this is line 2                                                        :|
|  : > more lines                                                            :|
|  : > more data                                                             :|
|  : > another line                                                          :|
|  :                                                                            :|
|  :                                                                            :|
|  :                                                                            :|
|  :                                                                            :|
|  :                                                                            :|
|  :                                                                            :|
|  :                                                                            :|
|  :                                                                            :|
|  :                                                                            :|
|  :                                                                            :|
|  :                                                                            :|
|  :  ===> __________________________________________________________________:|
|  :  ________________________________________________________________________  :|
|  : F4=Move  F5=Resize                                                         :|
|  : F6=Print                                                                   :|
|  :                                                                            :|
|  :............................................................................:|
|                                                                                |
+--------------------------------------------------------------------------------+