Using Sun WorkShop

Browsing Source With `sbquery`

The sbquery command provides you with a command-line browsing environment that you can access from terminals and from workstations emulating terminals.

Understanding `sbquery`

The command-line interface to the Source Browsing mode of Sun WorkShop is sbquery.

To issue a query from the command line, type sbquery, followed by any command-line options and their arguments, followed by the symbol you want to search for:

sbquery [options] symbols

All lines that contain symbols are displayed.

sbquery displays a list of matches that includes the file in which the symbol appears, the line number, the function containing the symbol, and the source line containing the symbol.

By default, sbquery searches for symbols in the database in the current working directory. If you want to browse a database stored in another directory, see "Controlling the Browser Database With sb_init".

Command Reference

To obtain a list of the sbquery command-line options, type sbquery at the shell prompt. Table D-1 lists and describes the options.

Table D-1 sbquery Options


Arguments	Description
`-break_lock`	Breaks the lock on a locked database. This argument might be needed if the update of the index file is aborted. The next time you issue a query you might get a message telling you that the database is locked. After using this option, your database may be in an inconsistent state. To ensure consistency, remove the database directory and recompile your program.
`-help`	Displays a synopsis of the `sbquery` command. Equivalent to typing `sbquery` with no options.
`-help_focus`	Displays a list of the focus options available for querying only specific program types in a directory. Use focus options to issue a query limited to specific units of code such as programs or functions.
`-help_filter`	Displays a list of the languages for which filter options are available. Use filtering options to search for symbols based on how they are used in a program.
`max_memory` `size`	Sets the approximate amount of memory, in megabytes, that should be allocated before `sbquery` uses temporary files when building the index file.
`-no_update`	Does not rebuild the index file when you issue a query following compilation. If you do not include this option and issue a query following compilation or recompilation, then the database updates and processes your query.
`-o` `file`	Sends query output to a file.
`-show_db_dirs`	Lists all database directories scanned when you issue a query. The list includes the following: the database directory in the current working directory and all other database directories specified by the `import` or `export` commands in your `sb_init` file.
`-version \| -V`	Displays the current version number.
`-files_only`	Lists only the files where the symbols you are searching for appear.
`-no_secondaries`	Returns only the primary match. A secondary match is an identifier inside a macro. You might want to turn off secondary matches if you are doing a lot of filtered querying, and the symbols you are querying on are used in a lot of macros.
`-no_source`	Displays only the file name and line number associated with each match.
`-symbols_only`	Displays a list of all symbols that match the patterns in your search pattern. Useful when you use wildcards in a query.
`-pattern` `symbol`	Queries on `symbol`, which may contain special characters, including a leading dash (-). This option allows you to query on a symbol that looks like a command-line option. For instance, you can query on the symbol `-help`, and `sbquery` distinguishes it from the regular option `-help`.
`-no_case`	Makes the query case-insensitive.
`-sh_pattern`	Uses shell-style expressions when issuing a query that includes wildcards. This wildcard setting is the default; include this option if you are doing other pattern matching on the same command line. See `sh(1)` for more information about shell-style pattern matching.
`-reg_expr`	Uses regular expressions when issuing a query that includes wildcards. If you do not include this option, shell-style patterns are assumed.
`-literal`	Does not use any wildcard expressions for the query. Useful when you want to search for a string that contains meta characters from other wildcard schemes.

Two types of options are available to help you narrow your search: filter options (see Table D-2) and focus options (see Table D-3.)

Filter Language Options

The filter options listed in Table D-2 are used to search for symbols based on how they are used in a program. For example, you could limit your search to declarations of variables.

sbquery -help_filter language

Table D-2 Filter Language Options


Filter Option	Description
`ansi_c`	C
`sun_as`	Assembly language
`sun_c_plus_plus`	C++
`sun_f77`	FORTRAN 77
`sun_f90`	Fortran 90

Focus Options

The focus options listed in Table D-3 limit your search to specific classes of code, such as particular programs, functions, or libraries.

sbquery focus_option symbol

Table D-3 Focus Options


Focus Option	Description
`-in_program` `program`	Limit query to matches in program.
`-in_directory` `directory`	Limit query to matches in directory.
`-in_source_file` `source_file`	Limit query to matches in source_file.
`-in_function` `function`	Limit query to matches in function.
`-in_class` `class`	Limit query to matches in class.
`-in_template` `template`	Limit query to matches in template.
`-in_language` `language`	Limit query to matches in language.

Note -

If you include two or more focus options, a match is returned if it is found with any of the supplied focus options.

Environment Variables

Environment variables provide information that affects the operation of sbquery (and of source browsing in Sun WorkShop). For more information on sb_init, see "Controlling the Browser Database With sb_init"."

Table D-4 Environment Variables


Variable	Description
`HOME`	The name of your login directory
`PWD`	The full path name of the current directory
`SUNPRO_SB_ATTEMPTS_MAX`	The maximum number of times the index builder tries to access a locked database
`SUNPRO_SB_EX_FILE_NAME`	The absolute path name of the file `sun_source_browser.ex`
`SUNPRO_SB_INIT_FILE_NAME`	The absolute path name of the `sb_init` file