Microsoft Access: VBA Programming Code

Provided by Allen Browne, June 2008.


Concatenate values from related records

You have set up a one-to-many relationship, and now you want a query to show the records from the table on the ONE side, with the items from the MANY side beside each one. For example if one company has many orders, and you want to list the order dates like this:

Company Order Dates
Acme Corporation 1/1/2007, 3/1/2007, 7/1/2000, 1/1/2008
Wright Time Pty Ltd 4/4/2007, 9/9/2007
Zoological Parasites  

JET SQL does not provide an easy way to do this. A VBA function call is the simplest solution.

How to use the function

Add the function to your database:

  1. In Access, open the code window (e.g. press Ctrl+G.)
  2. On the Insert menu, click Module. Access opens a new module window.
  3. Paste in the function below.
  4. On the Debug menu, click Compile, to ensure Access understands it.

You can then use it just like any of the built-in functions, e.g. in a calculated query field, in the ControlSource of a text box on a form or report, in a macro or in other code.

For the example above, you could set the ControlSource of a text box to:
     =ConcatRelated("OrderDate", "tblOrders", "CompanyID = " & [CompanyID])
or in a query:

SELECT CompanyName,  ConcatRelated("OrderDate", "tblOrders", "CompanyID = " & [CompanyID])
FROM tblCompany;

Bug warning: If the function returns more than 255 characters, and you use it in a query as the source for another recordset, a bug in Access may return garbage for the remaining characters.

The arguments

Inside the brackets for ConcatRelated(), place this information:

  1. First is the name of the field to look in. Include square brackets if the field contains non-alphanumeric characters such as a space, e.g. "[Order Date]"
  2. Second is the name of the table or query to look in. Again, use square brackets around the name if it contains spaces.
  3. Thirdly, supply the filter to limit the function to the desired values. This will normally be of the form:
        "[ForeignKeyFieldName] = " & [PrimaryKeyFieldName]
    If the foreign key field is Text (not Number), include quote marks as delimiters, e.g.:
        "[ForeignKeyFieldName] = """ & [PrimaryKeyFieldName]   & """"
    For an explanation of the quotes, see Quotation marks within quotes.
    Any valid WHERE clause is permitted.
    If you omit this argument, ALL related records will be returned.
  4. Leave the fourth argument blank if you don't care how the return values are sorted.
    Specify the field name(s) to sort by those fields.
    Any valid ORDER BY clause is permitted.
    For example, to sort by [Order Date] with a secondary sort by [Order ID], use:
        "[Order Date], [Order ID]"
    You cannot sort by a multi-valued field.
  5. Use the fifth argument to specify the separator to use between items in the string.
    The default separator is a comma and space.

Public Function ConcatRelated(strField As String, _
    strTable As String, _
    Optional strWhere As String, _
    Optional strOrderBy As String, _
    Optional strSeparator = ", ") As Variant
On Error GoTo Err_Handler
    'Purpose:   Generate a concatenated string of related records.
    'Return:    String variant, or Null if no matches.
    'Arguments: strField = name of field to get results from and concatenate.
    '           strTable = name of a table or query.
    '           strWhere = WHERE clause to choose the right values.
    '           strOrderBy = ORDER BY clause, for sorting the values.
    '           strSeparator = characters to use between the concatenated values.
    'Notes:     1. Use square brackets around field/table names with spaces or odd characters.
    '           2. strField can be a Multi-valued field (A2007 and later), but strOrderBy cannot.
    '           3. Nulls are omitted, zero-length strings (ZLSs) are returned as ZLSs.
    '           4. Returning more than 255 characters to a recordset triggers this Access bug:
    '               http://allenbrowne.com/bug-16.html
    Dim rs As DAO.Recordset         'Related records
    Dim rsMV As DAO.Recordset       'Multi-valued field recordset
    Dim strSql As String            'SQL statement
    Dim strOut As String            'Output string to concatenate to.
    Dim lngLen As Long              'Length of string.
    Dim bIsMultiValue As Boolean    'Flag if strField is a multi-valued field.
    
    'Initialize to Null
    ConcatRelated = Null
    
    'Build SQL string, and get the records.
    strSql = "SELECT " & strField & " FROM " & strTable
    If strWhere <> vbNullString Then
        strSql = strSql & " WHERE " & strWhere
    End If
    If strOrderBy <> vbNullString Then
        strSql = strSql & " ORDER BY " & strOrderBy
    End If
    Set rs = DBEngine(0)(0).OpenRecordset(strSql, dbOpenDynaset)
    'Determine if the requested field is multi-valued (Type is above 100.)
    bIsMultiValue = (rs(0).Type > 100)
    
    'Loop through the matching records
    Do While Not rs.EOF
        If bIsMultiValue Then
            'For multi-valued field, loop through the values
            Set rsMV = rs(0).Value
            Do While Not rsMV.EOF
                If Not IsNull(rsMV(0)) Then
                    strOut = strOut & rsMV(0) & strSeparator
                End If
                rsMV.MoveNext
            Loop
            Set rsMV = Nothing
        ElseIf Not IsNull(rs(0)) Then
            strOut = strOut & rs(0) & strSeparator
        End If
        rs.MoveNext
    Loop
    rs.Close
    
    'Return the string without the trailing separator.
    lngLen = Len(strOut) - Len(strSeparator)
    If lngLen > 0 Then
        ConcatRelated = Left(strOut, lngLen)
    End If

Exit_Handler:
    'Clean up
    Set rsMV = Nothing
    Set rs = Nothing
    Exit Function

Err_Handler:
    MsgBox "Error " & Err.Number & ": " & Err.Description, vbExclamation, "ConcatRelated()"
    Resume Exit_Handler
End Function

Home Index of tips Top