Conference orarep::nomahs::sql_services

2141.0. "How to use SQL/Services memory debugging" by SQLSRV::OXBURY (Oracle Corporation, Rdb Desktop Group|DTN 381-2704) Tue Feb 11 1997 13:55

Hi folks,

This note describes how to use SQL/Services memory debugging. It is built into
the SQL/Services V6.1-02 executor and into the SQL/Services V7.0 executor and
client API.

	IMPORTANT: PLEASE NOTE ALL THE CAVEATS REGARDING ITS USE. 

Remember executor protocol logging, which was not and is still not documented,
and which sometimes used to cause the executor to ACCVIO?? Well, although
significant use has been made of the memory debugging functionality in the
executor during SQL/Services 7.0 load testing (though not in the client API)
there is still no guarantee that something nasty might not happen if you try to
use it. [For what its worth, executor protocol logging is believed to be
working correctly in SQL/Services 7.0, but again there are no guarantees. (Too
much code had to be changed to back-port it to V6.1-02.)]

Following are the comments from the code on how to use it. One last point:
remember that SQL/Services isn't the only component in an executor process;
SQL, Rdb dispatch and the Rdb engine (unless going remote or using some other
engine) are also in there and using memory. All of which means that all that
SQL/Services memory debugging might illustrate is that SQL/Services itself
isn't eating up memory.

Si

Ps, this is very definitely a what-you-see-is-what-you-get feature. Please
don't ask for extensions to it, better ways to turn it on and off, better
client support, and so forth. This was designed to be an internal-use tool (so
we could make sure we weren't leaking memory before shipping something) and was
intended only for customer use as a last resort; beside, no one has time to
make it any better.

Sample output (for 4 sessions):

****MEMDBG: initialized
****MEMDBG: total malloc()/free(): 0/0, current count: 0
****MEMDBG: total malloc()/free(): 11/0, current count: 11
****MEMDBG: total malloc()/free(): 13/2, current count: 11
****MEMDBG: total malloc()/free(): 15/4, current count: 11
****MEMDBG: total malloc()/free(): 28/17, current count: 11
****MEMDBG: total malloc()/free(): 40/29, current count: 11
------------EVENT BEGIN:  EVENT_LOG at Tue Feb 11 1997 13:53:58.384-------------
%SQLSRV-I-EVENT_LOG, event logged at line 9199 in file CMD.C;1
%SQLSRV-I-SM_EXECSHUT, Shutting down executor GENERI0040001
------------EVENT END  :  EVENT_LOG at Tue Feb 11 1997 13:53:58.385-------------
****MEMDBG: total malloc()/free(): 40/40, current count: 0
****MEMDBG: finished

Instructions for use:

/*+
 * sqlsrv_memory_debug_init(): Initialize memory debugging
 *
 * Description:
 *
 *	------------------------- Note -------------------------
 *	Memory debugging was developed as an internal tool to
 *	track memory usage problems in the executor. It has 
 *	been extended to allows its use with certain clients, but
 *	with limited support on some client platforms. Memory 
 *	debugging is NOT a SUPPORTED feature of the SQL/Services
 *	client or server; therefore, there are no guarantees that
 *	enabling its use may not introduce other problems.
 *	------------------------- Note -------------------------
 *
 *  Initializes one or more SQL/Services memory debugging options.
 *
 *  Flags/options:
 *
 *	SQLSRV_MEMDBG_STATS (1): 
 *	    If the statistics flag is set, we keep track of the number of calls 
 *	    to sqlsrv_malloc() and sqlsrv_free(). This provides a simple test 
 *	    to determine if SQL/Services is not releasing memory when it should.
 *	    In the client, a client log file is opened and the final counts are
 *	    written to the log when sqlsrv_release() is called. In the server,
 *	    the counters are written to the executor's log file whenever a 
 *	    client association is released and when the executor is shut down.
 *
 *	SQLSRV_MEMDBG_CHECK (2):
 *	    If the memory-check flag is set, sqlsrv_malloc() will allocate the 
 *	    requested number of bytes plus space for a header and a trailer 
 *	    block. The header block contains a flink/blink combination (server)
 *	    or a next pointer (client), size, allocator ID (module ID and line
 *	    number), allocation number, plus a 32-bit or 64-bit sanity-check 
 *	    field. The trailer also contains a sanity-check field, plus 
 *	    duplicates of the size, allocation number and allocator ID from 
 *	    the header. Both header and trailer are used to detect memory 
 *	    writes either side of the allocated block. sqlsrv_malloc() inserts 
 *	    the header onto an allocated list, while sqlsrv_free() removes the 
 *	    header after verifying the block is on the list. If an no-memory 
 *	    condition is detected, sqlsrv_malloc() optionally dumps the 
 *	    allocated block list.
 *
 *	SQLSRV_MEMDBG_DMPNOMEM (4):
 *	    If the dump-on-no-memory-error flag is set, the first few bytes of
 *	    all allocated blocks of memory will be dumped. Forces the
 *	    SQLSRV_MEMDBG_CHECK flag.
 *
 *      SQLSRV_MEMDBG_CHECKSTMQ [6.1-ONLY; OBSOLETE AS OF 7.0] (8):
 *          If the check-statement-queue flag is set, we will walk the 
 *          statement queue on each malloc/free.  We do this by calling 
 *          sqlsrv_getstmstmid with an invalid statement id.  V6.1 executor
 *          only.
 *
 *	SQSLRV_MEMDBG_CHECKEXEC (16):
 *	    Validate allocated memory before and after executing each request.
 *	    Assumes SQLSRV_MEMDBG_CHECK has been set, but doesn't force it
 *	    until SQL/Services V8.0.
 *
 *	SQLSRV_MEMDBG_TRACE (32)
 *	    Trace all calls to sqlsrv_malloc() and sqlsrv_free(). Warning,
 *	    setting this flag may generate lots of trace information. This
 *	    doesn't force SQLSRV_MEMDBG_CHECK, but more information is 
 *	    displayed if its sets.
 *
 *  Notes:
 *
 *	General:
 *	    Just add up the options you want, then define the appropriate
 *	    logical, set the appropriate environment variable, and so on,
 *	    according to the component and platform.
 *
 *	Executor: 
 *	    OpenVMS:
 *		Define the SQLSRV$MEMORY_DEBUG_FLAGS logical as a:
 *		    - system logical for all services or, preferably, 
 *		    - process logical in an initialization file for a specific 
 *		      service.
 *	    Unix:
 *		Set the SQLSRV_MEMORY_DEBUG_FLAGS environment variable:
 *		    - before starting the server in the process from which the
 *		      the server will be started using START SERVER for all
 *		      services, or preferably,
 *		    - in a .dbsrc file for a specific service.
 *	    All output is written to the executor log. Note that the executor
 *	    allocates memory only when it needs it. Therefore, if a particular
 *	    aspect of functionality is not used by the first association, but 
 *	    is used by the second association, it might appear that the 2nd
 *	    association caused memory to be allocated but not released.
 *	    However, this is not normally the case, as subsequent associations
 *	    will use the memory allocated by the 2nd association.
 *
 *	Clients in general:
 *	    All output is written to the client log. If client logging is
 *	    not enabled, a client log will still be created and written if
 *	    memory debugging is enabled, but no protocol or call information
 *	    will be written to the client log. If protocol or call logging is
 *	    enabled, it will be interspersed with the memory debugging output.
 *
 *	OpenVMS and Unix-based clients: 
 *	    Define the SQLSRV$MEMORY_DEBUG_FLAGS logical on OpenVMS or 
 *	    SQLSRV_MEMORY_DEBUG_FLAGS environment variable on Unix. 
 *
 *	Windows-based clients:
 *	    Set the MemoryDebugFlags option variable in the SQSAPIW.INI or 
 *	    SQSAPI32.INI file. Note that you have to add a definition for
 *	    this option variable; .INI files shipped with the kit do not
 *	    contain a definition that has been commented out. Do not use
 *	    the SQLSRV_LOG_OPNCLS (64) option with memory debugging; if
 *	    you try it, the call to sqlsrv_associate will fail with a GPF.
 *	    SQLSRV_LOG_FLUSH (128) may or may not work (its not been tested).
 *	    The SQLSRV_MEMDBG_CHECK and SQLSRV_MEMDBG_DMPNOMEM options are
 *	    not currently available on Windows due to the necessity to lock
 *	    memory; enabling them may cause GPFs and other unexplained errors.
 *	    SQLSRV_MEMDBG_TRACE is available.
 *
 *	Mac clients:
 *	    Limited memory debugging is available on the Mac by setting some
 *	    undocumented (ie, the symbols are NOT #define'd) client logging 
 *	    flags: SQLSRV_LOG_MEMDBGSTATS (8192) and SQLSRV_LOG_MEMDBGTRACE
 *	    (16384). The SQLSRV_MEMDBG_CHECK and SQLSRV_MEMDBG_DMPNOMEM 
 *	    options are not currently available on Windows due to the use of
 *	    handles on the Mac.
 *	    
 * returns:
 *  VOID
 */