Standard and Enhanced Interface Considerations
There is no functional difference between the standard and enhanced
EHLLAPI interfaces on a given platform. However there are other important
differences:
- The enhanced EHLLAPI interface extends the presentation space ID (PSID) from 1 byte to 4 bytes. Currently the additional bytes are not used, but your application should set them to binary zeros to ensure compatibility with future versions of enhanced EHLLAPI.
- The position (offset) of data elements in memory buffers passed to and from EHLLAPI functions are different. Data elements in enhanced EHLLAPI are aligned to double-word boundaries. Data elements in standard EHLLAPI are not aligned in any particular way. EHLLAPI applications should not be coded to set or retrieve data in the buffers by offset (byte) values. Instead, the supplied data structures in the HAPI_C.H file should be used to set and retrieve data elements. This will ensure that data is set and retrieved from the correct position for both 16- and 32-bit programs.
By prefilling EHLLAPI data buffers with binary zeros, and using
the data structures supplied in HAPI_C.H, an application can be compiled
for standard or enhanced operation without any source code changes.
For example, the following section of code
would work for standard EHLLAPI but would fail for enhanced EHLLAPI:
#include "hapi_c.h"
...
int Func, Len, Rc;
char Buff[18];
char SessType;
Func = HA_QUERY_SESSION_STATUS; // Function
Len = 18; // Buffer length
Rc = 0;
Buff[0] = 'A' // Session to query
hllapi(&Func, Buff, &Len, &Rc); // Execute function
SessType = Buff[9]; // Get session type
...
The above example would fail if compiled as a enhanced EHLLAPI
application because:
- The application does not set the extended session ID bytes to zero.
- The buffer length for this function is 20, not 18.
- The session type indicator is not at offset 9 in the data buffer, it is at offset 12.
The following is the same function written to work correctly if
compiled for standard or enhanced operation. Changed lines are indicated
with a >:
#include "hapi_c.h"
...
int Func, Len, Rc;
> struct HLDQuerySessionStatus Buff;
char SessType;
Func = HA_QUERY_SESSION_STATUS; // Function
> Len = sizeof(Buff); // Buffer length
Rc = 0;
> memset(&Buff, 0x00, sizeof(Buff));// Zero buffer
> Buff.qsst_shortname = 'A'; // Session to query
hllapi(&Func, (char *)&Buff, &Len, &Rc); // Execute function
> SessType = Buff.qsst_sestype; // Get session type
...