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
   ...