##RS Tag

The system is capable of parsing out up to 9 result sets. The ##RS tag allows the developer the ability to document each of the named columns parsed out. The ##RS tag is immediately followed by a number indicating the result set the parameter belongs too.

Since the ##RS is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##RS line is intended to be a multiline comment, a ##RS must appear on the line immediately before the text to form part of the comment.

The values returned from the ##RS tag can be overridden with the ##OV tag.

When defining multiple result sets from a given procedure, use the ##RSD tag to define the intent of each result set.

Note: When documenting the command SELECT * FROM Table, the column name is not * but rather Table.*

Note: Since a procedure might return more than one result set depending upon the path of execution in the procedure, or could return the same column alias template for multiple paths of execution, it is not uncommon to find the same result set described more than once.

Note: If a result set does not use named columns, SQLHelp will assign a name of Unnamed column #nnn, where nnn is the ordinal of the column in the result set.

Note: If a result set has column names which are duplicated, SQLHelp will assign an ordinal offset to the column name to provide for uniqueness.  Thus if a named column of Products were repeated in the same result set, the second time it would appear as Products #nnn, where nnn represents the duplicate columns ordinal in the output result set.

 

Syntax

##RSNumber Column ^^ Comment

Where Number is the number of the result set as it appears in the batch,
Where
Column is the name of the column,
and
Comment is the documentation text to use

Examples

-- ##RS1 ProductName ^^ The product name.

-- ##RS2 SupplierName ^^ The supplier name.

-- ##RS2 Supplier Sku ^^ The SKU Number associated with the product as defined by the supplier.

-- ##RS3 Sales.* ^^ All columns from the sales table

Sample Output

During SQL parsing, SQLHelp attempts to determine all result sets returned from the procedure.  If there is only one result set, the output file will contain a header labeled Output Recordset.  If more than one result set was found, each one will be numbered as in this sample.  Please note that the values are listed as found.  Thus for this result set, the first column is labeled UserType.

Occasionally you might find the a description value that contains the phrase Dynamic Column.  This normally will occur if the procedure returns different column aliases for the same absolute column position, or contains a column alias that is built from the concatenation of one or more strings.  While perfectly legitimate, this SQL could pose difficulties for procedure consumers (via ADO or other access means) who expect specific column names to be present in the result set.

© 2001-2004 Pikauba Software. All rights reserved.