51e4a3653e388862ee69692a7aea7a3c753840ef
galt
  Fri Jun 14 16:18:56 2013 -0700
improving comments, making comments consistent between jksql.c,h and fixing one reference to a renamed function in pubsTracks.c
diff --git src/hg/lib/jksql.c src/hg/lib/jksql.c
index 9f29626..0317f20 100644
--- src/hg/lib/jksql.c
+++ src/hg/lib/jksql.c
@@ -3029,31 +3029,31 @@
     int inputSize = end - s;
     int worstCase = inputSize*2 + 1;
     if (worstCase > remainder)
 	errAbort("Buffer too small for escaping in sqlEscapeAllStrings. s=[%s] bufSize = %d", sOrig, bufSize);
     int escSize = mysql_escape_string(buffer, s, inputSize);
     buffer += escSize;
     sz += escSize;
     remainder -= escSize;
     s = end + 1;	
     }
 return sz;
 }
 
 
 int vaSqlSafefNoAbort(char* buffer, int bufSize, boolean newString, char *format, va_list args)
-/* Format string to buffer, vsprintf style, only with buffer overflow
+/* VarArgs Format string to buffer, vsprintf style, only with buffer overflow
  * checking.  The resulting string is always terminated with zero byte.
  * Scans string parameters for illegal sql chars. 
  * Automatically escapes quoted string values.
  * This function should be efficient on statements with many strings to be escaped. */
 {
 va_list orig_args;
 va_copy(orig_args, args);
 int formatLen = strlen(format);
 
 char escPunc = 0x01;  // using char 1 as special char to denote strings needing escaping
 //char escPunc = '`';  // DEBUG REMOVE
 char *newFormat = NULL;
 int newFormatSize = 2*formatLen + 1;
 if (newString)
     newFormatSize += strlen("NOSQLINJ ");
@@ -3224,94 +3224,100 @@
     }
 
 freeMem(newFormat);
 va_end(orig_args);
 va_end(args);
 
 return sz;
 
 }
 
 
 
 
 
 int vaSqlSafef(char* buffer, int bufSize, char *format, va_list args)
-/* Format string to buffer, vsprintf style, only with buffer overflow
+/* VarArgs Format string to buffer, vsprintf style, only with buffer overflow
  * checking.  The resulting string is always terminated with zero byte. */
 {
 int sz = vaSqlSafefNoAbort(buffer, bufSize, TRUE, format, args);
 if ((sz < 0) || (sz >= bufSize))
     {
     buffer[bufSize-1] = (char) 0;
     errAbort("buffer overflow, size %d, format: %s, buffer: '%s'", bufSize, format, buffer);
     }
 return sz;
 }
 
 int sqlSafef(char* buffer, int bufSize, char *format, ...)
 /* Format string to buffer, vsprintf style, only with buffer overflow
  * checking.  The resulting string is always terminated with zero byte. 
  * Scans unquoted string parameters for illegal literal sql chars.
- * Escapes quoted string parameters. */
+ * Escapes quoted string parameters. 
+ * NOSLQINJ tag is added to beginning. */
 {
 int sz;
 va_list args;
 va_start(args, format);
 sz = vaSqlSafef(buffer, bufSize, format, args);
 va_end(args);
 return sz;
 }
 
 
 int vaSqlSafefFrag(char* buffer, int bufSize, char *format, va_list args)
-/* Format string to buffer, vsprintf style, only with buffer overflow
+/* VarArgs Format string to buffer, vsprintf style, only with buffer overflow
  * checking.  The resulting string is always terminated with zero byte. 
- * This version does not add the NOSQLINJ tag since it is assumed to be just a fragment of
+ * Scans unquoted string parameters for illegal literal sql chars.
+ * Escapes quoted string parameters. 
+ * NOSLQINJ tag is NOT added to beginning since it is assumed to be just a fragment of
  * the entire sql string. */
 {
 int sz = vaSqlSafefNoAbort(buffer, bufSize, FALSE, format, args);
 if ((sz < 0) || (sz >= bufSize))
     {
     buffer[bufSize-1] = (char) 0;
     errAbort("buffer overflow, size %d, format: %s, buffer: '%s'", bufSize, format, buffer);
     }
 return sz;
 }
 
 int sqlSafefFrag(char* buffer, int bufSize, char *format, ...)
 /* Format string to buffer, vsprintf style, only with buffer overflow
  * checking.  The resulting string is always terminated with zero byte. 
- * Scans string parameters for illegal sql chars. 
- * This version does not add the NOSQLINJ tag since it is assumed to be just a fragment of
+ * Scans unquoted string parameters for illegal literal sql chars.
+ * Escapes quoted string parameters. 
+ * NOSLQINJ tag is NOT added to beginning since it is assumed to be just a fragment of
  * the entire sql string. */
 {
 int sz;
 va_list args;
 va_start(args, format);
 sz = vaSqlSafefFrag(buffer, bufSize, format, args);
 va_end(args);
 return sz;
 }
 
 
 
 /* --------------------------- */
 
 
-void sqlDyStringVaPrintfExt(struct dyString *ds, boolean isFrag, char *format, va_list args)
-/* VarArgs Printf to end of dyString after scanning string parameters for illegal sql chars. */
+void vaSqlDyStringPrintfExt(struct dyString *ds, boolean isFrag, char *format, va_list args)
+/* VarArgs Printf to end of dyString after scanning string parameters for illegal sql chars.
+ * Strings inside quotes are automatically escaped.  
+ * NOSLQINJ tag is added to beginning if it is a new empty string and isFrag is FALSE. */
 {
 /* attempt to format the string in the current space.  If there
  * is not enough room, increase the buffer size and try again */
 int avail, sz;
 while (TRUE)
     {
     va_list argscp;
     va_copy(argscp, args);
     avail = ds->bufSize - ds->stringSize;
     if (avail <= 0)
         {
         /* Don't pass zero sized buffers to vsnprintf, because who knows
          * if the library function will handle it. */
         dyStringBumpBufSize(ds, ds->bufSize+ds->bufSize);
         avail = ds->bufSize - ds->stringSize;
@@ -3320,82 +3326,91 @@
     va_end(argscp);
 
     /* note that some version return -1 if too small */
     if ((sz < 0) || (sz >= avail))
 	{
         dyStringBumpBufSize(ds, ds->bufSize+ds->bufSize);
 	}
     else
         {
         ds->stringSize += sz;
         break;
         }
     }
 }
 
-void sqlDyStringVaPrintf(struct dyString *ds, char *format, va_list args)
-/* VarArgs Printf to end of dyString after scanning string parameters for illegal sql chars. */
+void vaSqlDyStringPrintf(struct dyString *ds, char *format, va_list args)
+/* VarArgs Printf to end of dyString after scanning string parameters for illegal sql chars.
+ * Strings inside quotes are automatically escaped.  
+ * NOSLQINJ tag is added to beginning if it is a new empty string. */
 {
-sqlDyStringVaPrintfExt(ds, FALSE, format, args);
+vaSqlDyStringPrintfExt(ds, FALSE, format, args);
 }
 
 void sqlDyStringPrintf(struct dyString *ds, char *format, ...)
-/* Printf to end of dyString after scanning string parameters for illegal sql chars. */
+/* Printf to end of dyString after scanning string parameters for illegal sql chars.
+ * Strings inside quotes are automatically escaped.  
+ * NOSLQINJ tag is added to beginning if it is a new empty string. */
 {
 va_list args;
 va_start(args, format);
-sqlDyStringVaPrintf(ds, format, args);
+vaSqlDyStringPrintf(ds, format, args);
 va_end(args);
 }
 
-void sqlDyStringVaPrintfFrag(struct dyString *ds, char *format, va_list args)
+void vaSqlDyStringPrintfFrag(struct dyString *ds, char *format, va_list args)
 /* VarArgs Printf to end of dyString after scanning string parameters for illegal sql chars. 
- * NOSLQINJ tag is not added. */
+ * Strings inside quotes are automatically escaped.
+ * NOSLQINJ tag is NOT added to beginning since it is assumed to be just a fragment of
+ * the entire sql string. */
 {
-sqlDyStringVaPrintfExt(ds, TRUE, format, args);
+vaSqlDyStringPrintfExt(ds, TRUE, format, args);
 }
 
 void sqlDyStringPrintfFrag(struct dyString *ds, char *format, ...)
 /* Printf to end of dyString after scanning string parameters for illegal sql chars. 
- * NOSLQINJ tag is not added. */
+ * Strings inside quotes are automatically escaped.
+ * NOSLQINJ tag is NOT added to beginning since it is assumed to be just a fragment of
+ * the entire sql string. */
+
 {
 va_list args;
 va_start(args, format);
-sqlDyStringVaPrintfFrag(ds, format, args);
+vaSqlDyStringPrintfFrag(ds, format, args);
 va_end(args);
 }
 
 
 void sqlDyStringAppend(struct dyString *ds, char *string)
 /* Append zero terminated string to end of dyString.
- * Makes sure the NOSQLINJ prefix gets added if needed */
+ * Adds the NOSQLINJ prefix if dy string is empty. */
 {
 if (ds->stringSize == 0)
     dyStringAppend(ds, "NOSQLINJ ");
 dyStringAppendN(ds, string, strlen(string));
 }
 
 
 struct dyString *sqlDyStringCreate(char *format, ...)
 /* Create a dyString with a printf style initial content 
- * Makes sure the NOSQLINJ prefix gets added if needed */
+ * Adds the NOSQLINJ prefix. */
 {
 int len = strlen(format) * 3;
 struct dyString *ds = newDyString(len);
 va_list args;
 va_start(args, format);
-sqlDyStringVaPrintf(ds, format, args);
+vaSqlDyStringPrintf(ds, format, args);
 va_end(args);
 return ds;
 }
 
 
 void sqlCheckError(char *format, ...)
 /* A sql injection error has occurred. Check for settings and respond
  * as appropriate with error, warning, logOnly, ignore, dumpstack.
  * Then abort if needed. NOTE: unless it aborts, this function will return! */
 {
 va_list args;
 va_start(args, format);
 
 char *noSqlInjLevel = cfgOption("noSqlInj.level");
 char *noSqlInjDumpStack = cfgOption("noSqlInj.dumpStack");