Click above to get retro games delivered to your door ever month!

 Using NOVLIB with C
------------------------------------------------------------------------------
 NOVLIB supports most C compilers, including Microsoft C/C++, Borland C/C++,
 Symantec C/C++ and WATCOM C++. Currently 32 bit programming is supported
 under Windows 95 only.
 Two header files containing function prototypes are provided, NOVLIBC.H and
 NOVLIBP.H. NOVLIBC.H provides prototypes for NOVLIB functions called using
 both the standard C calling convention (16 bit) and stdcall convention (32
 bit), and NOVLIBP.H provides prototypes for NOVLIB functions called using
 the PASCAL calling convention (16 bit only).
 When using the statically linked 16 bit library, (NOVLIB.LIB), all calls to
 NOVLIB functions must use the standard C calling convention, but when using
 the NOVLIB.DLL, you may make use of either the standard C calling
 convention, or the PASCAL calling convention.

 NOVLIB and C Strings

 Due to the nature of C with regard to the handling of strings, there is one
 important consideration which applies to C that does not apply to the other
 languages supported by NOVLIB, namely allocation of memory for returned
 string or binary data.
 When calling any NOVLIB function that returns a string, it is the
 programmer's responsibility to pass a far pointer to a buffer of the
 correct size as the last argument to the function. NOVLIB will copy the
 returned string into this buffer and return a pointer to this buffer as the
 function return value. If you do not want to examine the return value, you
 may pass a NULL pointer in place of the buffer pointer, in which case the
 returned pointer is undefined.
 The maximum size of the returned string is documented in the function
 reference, but note that this does not include the extra byte for the
 string terminator required by C, so memory allocations should be one byte
 larger than the documented size.

 For example, the function UsrFullNameSet() which sets the full name of the
 specified user is documented as taking two arguments, a pointer to the name
 of the user and a pointer to the full name of the user. The function
 returns a string which is up to 127 characters in length:

 lpszOldName = UsrFullNameSet(lpszUserName, lpszNewFullName)

 However, when called from C, the function expects an additional argument, a
 far pointer to a buffer into which NOVLIB is to copy the previous full
 name. Therefore, the function should be called as follows:

 LPSZ lpszBuffer, lpszOld;

 lpszBuffer = malloc(128);  // one extra byte for the terminator
 lpszOld = UsrFullNameSet(lpszName, lpszFullName, lpszBuffer);
 printf("The user's previous full name was %s\n",lpszOld);
 free(lpszBuffer);       // lpszOldName now invalid!

 NOVLIB will copy the previous full name into the buffer pointed to by
 lpszBuffer, and the pointer returned from the function will point to this
 buffer. If the previous full name is not of interest, the function can be
 called with a NULL pointer in place of lpszBuffer:

 UsrFullNameSet(lpszObjectName, lpszFullName, 0L);

 Similarly the function UsrFullNameGet() is documented as taking one
 argument, the name of the user, and returns the current full name:

 lpszFullName = UsrFullNameGet(lpszUserName)

 When called from C, the function expects an additional argument, a far
 pointer to a buffer in which to store the full name. The function should
 therefore be called as follows:

 LPSZ lpszBuffer, lpszFullName;

 lpszBuffer = malloc(128);
 lpszFullName = UsrFullNameGet(lpszName, lpszUserBuffer);
 printf("The user's current full name is %s\n",lpszName);
 free(lpszUserBuffer);      // Note: lpszName now invalid

 Linking (16 bit)

 NOVLIB is provided in both .LIB and .DLL formats. When linking 16 bit DOS
 programs, NOVLIB.LIB and NOVDOS.LIB should be linked, when linking 16 bit
 Windows programs that use NOVLIB.DLL, only the import library NOVIMP.LIB
 should be linked. When linking Windows programs that use the static
 libraries, NOVLIB.LIB and NOVWIN.LIB should be linked. If the Microsoft or
 Borland linker is being used, the following general formats apply:
 DOS:

 LINK <objects>,<exefile>,<map>,NOVLIB+NOVDOS
 TLINK <objects>,<exefile>,<map>,NOVLIB+NOVDOS

 Windows (using DLL):

 LINK <objects>, <exefile>, <map>, NOVIMP, <deffile>
 TLINK <objects>, <exefile>, <map>, NOVIMP, <deffile>

 Windows (using static library):

 LINK <objects>, <exefile>, <map>, NOVLIB+NOVWIN, <deffile>
 TLINK <objects>, <exefile>, <map>, NOVLIB+NOVWIN, <deffile>

 Linking (32 bit)

 When linking 32 bit Windows programs (Windows 95 only), NOVLIB95.DLL must
 be used and one of two supplied import libraries should be linked (or added
 to your project) - NOVMVC95.LIB for Microsoft Visual C++, or NOVBCC95.LIB
 for Borland C++. If you are using a alternative C compiler, use
 NOVMVC95.LIB if your linker uses COFF format object modules, otherwise use
 NOVBCC95.LIB or build your own import library using the tool supplied by
 your compiler vendor. Note that static linking of NOVLIB is not supported
 for 32 bit programming - you must use the DLLs.