Buffer management

The buffer used to communicate with the client is limited to a maximum length of 32755 bytes. This has implications when sending or receiving large amounts of data with the client.  For data transmissions of less than 32755 bytes no special handling need occur.

For larger transmissions, the data must be split into multiple pieces as necessary with each piece being no larger than 32755 bytes. Then transmit all of the pieces until all of the pieces are transmitted. The sending side must split the data; the receiving side must put the pieces back together.  The handling of split data buffers in this fashion is the responsibility of the application programmer. The TPAPI does not perform this task for you.

When splitting data into multiple pieces, some mechanism is usually required in order to let the receiving side know how many pieces to expect. This can be accomplished several ways, with two possible options being to (1) send a count of the number of pieces that will be coming in the first transmission, or (2) to send an indicator byte or flag in the last piece of the transmission which indicates that this is the last piece.

Data conversion is also an important consideration in managing the size of the buffer used for transmission. Data converted from EBCDIC to UTF-8 will often be larger after the conversion. Thus, a full 32755-byte data string sent to a conversion service might be larger than 32755 bytes after the conversion. The result of the conversion in such a case must be split into multiple pieces before transmission. Larger post-conversion data lengths are very common if EBCDIC DBCS code pages (for example, CCSID 939) are being converted to UTF-8.  If data conversion services are used by your application, any code you write to perform data splits into multiple pieces should execute after data conversions are completed. Likewise, when receiving data that was split into multiple pieces, the pieces should be reassembled into its original size string before submitting that string to conversion services.

The length of the data to be transmitted to the client should be placed into the field TPBUFLEN in the TPAPIXIB structure. This length should not be larger than 32755 or an error condition will occur. When data is received from the client, the TPBUFLEN field will contain the actual length of the data received.

Any data received from the client is terminated by a X’00’ byte (LOW-VALUES). However, the length received does not count the X’00’ byte; the X’00’ terminator character is added by TPAPI as a convenience to PL/I and C programmers using string functions.