SAS/C Software: Changes and Enhancements, Release 6.50

Search Lists

This release of the SAS/C Debugger allows you to create search lists for specifying the identity and location of files used by the debugger. Search lists are created with the debugger's set search command and set cache command.

You can use search lists in any environment where you can run the SAS/C Debugger. However, they are particularly useful in the following situations:

when you develop applications in a cross-development environment, where compilations occur on a UNIX workstation using the SAS/C Cross-Platform Compiler
when you compile in batch or TSO and debug in the OpenEdition shell.

The following sections describe how to use set search and set cache to define search lists. While the discussion includes information about using search lists in a cross-development environment, it focuses on the mainframe environment. For details on using search lists in a cross-development environment, see SAS/C Cross-Platform Compiler and C++ Development System: Usage and Reference, First Edition.

Input file selection and specification

The SAS/C Debugger provides access to information from several different types of files, including:

debugger files
source files
alternate source files
system include files
user include files

When the default search procedure for a file does not meet your needs, it is possible to change this behavior by using the debugger's set search command.

The set search command is used to specify filename templates. Filename templates are used specify the identity and location of the source, include, or debugger files associated with the load module being debugged. Multiple filename templates can be defined for each type of file. So, when necessary, the debugger can search for a file by more than one name or in multiple locations. Each template is saved in a search list, and each search list is associated with a specific type of file.

Filename templates are character strings, which are patterned after the format argument of the C printf function. Each filename template can contain conversion specifiers and characters. A conversion specifier is a character or a string preceded by the percent (%) character. The conversion specifier is either replaced by its associated string or specifies the format of the conversion specifier that follows it. The resulting string is used as the name of the file to be opened. If the open fails the next filename template is processed until either a file is opened or no more filename templates are in the search list for that type of file.

This is a very powerful technique that allows you to direct the debugger to files that have moved or even changed names or file systems.

Note: If you run the debugger under the OpenEdition shell, the filename string is interpreted as an MVS filename, not as a POSIX filename. If you want to specify searching for a file in the OpenEdition hierarchical file system, you must begin the filename with the hfs: filename style prefix. [cautend]

Using the set Command

The SAS/C Debugger's set command provides two subcommands:

set search
set cache

The set search command is used to specify a search list consisting of one or more filename templates. Each filename template specifies a location used by the debugger to search for source, include, or debugger files associated with the load module being debugged. The debugger traverses the search list, looking for the file specified by each filename template.

The set cache command is used primarily in a cross-development environment, especially for large debugger files. This command uses a filename template to specify a location where debugger files are searched for, before the debugger uses the debug search list. In a typical cross-debugging session, this cache location would be on the mainframe.

The debugger first looks for the debugger file in the cache location. If the debugger file is found in the cache location, it is used, unless the module has been recompiled since the debugger file was generated. If the module has been recompiled, or if the debugger file is not found in the cache location, the debugger uses the normal search mechanism to locate the file, and then copies the file to the cache location.

Locating the debugger file

Load modules that have been generated from objects compiled by the SAS/C Compiler contain filename information for the debugger file. The format of this filename information depends on the host that performed the compilation and the file system the debugger file was created in. The debugger will look for the debugger file in the following locations in the order listed:

any cache location, as specified by the set cache command
any locations in the debug search list, as specified by the set search debug command
the filename the compiler used to open the file when it was created.

On MVS, if you have not specified a cache location or search list for the debugger file, the debugger uses a default search list for debugger files, which is equivalent to the following command:

set search debug = "//ddn:DBGLIB(%sname)";

The debugger will attempt to open the file by the name the compiler used when it created the file if the file is not found using the search list, or if the debug search list was cleared with a set search debug command of the form:

set search debug = ""

Note: If the load module being debugged was generated from objects created by the SAS/C Cross-Platform Compiler, the debugger uses the path: filename style prefix with the original filename. [cautend]

On CMS, there is no default debug search list. If the debugger file is not found using a search list defined by you, then the debugger will search for the file using its original filename. If the debugger is running under CMS Release 6 or later, it may search one or more shared file directories for the debugger file: If the _DB environment variable is set, each dirname or NAMEDEF specified using the _DB environment variable is searched.

If the debugger file is not found in a Shared File System directory, or you are using a CMS release earlier than 6, the debugger will try to open file fname DB *, where fname is the filename used by the compiler when it created the debugger file.

To append templates to the debug search list, use the following form of the set search command:

set search debug + "template1" 
  "template2" ...

To replace all templates in the debug search list, use the following form of the set search command:

set search debug = "template1" 
  "template2" ...

Locating source files

The debugger file contains filename information for the source files and alternate source files used to compile your program. The debugger will look for the source files in the following locations in the order listed:

any locations specified in the source search list, as specified by the set search command
the filename the compiler used to open the file when it was created.

On MVS, the debugger uses a default search list for source files, which is equivalent to the following command:

set search source = "//ddn:DBGSRC(%sname)";

If a file is not found using one of the templates in the source search list, the debugger attempts to open the file by the name the compiler used for the file.

The source search list is not checked for source files that have been altered by a #line preprocessor statement that specified a filename. Instead the separate altsource search list is used.

You can also use the following forms of the set search command to specify a new source search list to be used to locate these files:

set search source = "template1" 
  "template2" ...

set search altsource = "template1" 
  "template2" ...

Locating include files

The debugger file also contains filename information for the system include files and user include files used to compile your program. The different types of include file each have a separate search list. The debugger will look for an include file in the following locations in the order listed:

any locations in the associated search list, as specified by the set search command
the filename the compiler used to open the file.

You can use the following forms of the set search command to specify a new include search list to be used to locate these files:

set search systeminclude = "template1" 
  "template2" ...

set search userinclude = "template1" 
  "template2" ...

set Command Reference

The SAS/C Debugger's set command is best used in the debugger PROFILE or run command file to specify search lists for source, include, and debugger files, as well as a cache location for your debugger file. However, the set command may also be issued on the command line. The following reference section describes both the set search subcommand and set cache subcommand.

set

Controls file access

ABBREVIATION

se{t}

FORMAT

set subcommand subcommand-arguments

DESCRIPTION

The set command has two subcommands: search and cache. The set search command is used to control the definition of search templates that are used to access debugger and source files. The set cache command is used to specify a cache location for debugger files. The set cache command also uses a template to specify this location.

search SUBCOMMAND

The search subcommand is used to establish a search list, to control tracing, or remove templates from a search list. The search subcommand has the following forms:

Format 1:: set search file-tag =|+|- "template1 "
["template2 " ...]
Format 2:: set search file-tag =
Format 3:: set search file-tag| * ?
Format 4:: set search file-tag| * trace on | trace off

The file-tag argument specifies the type of file that a template applies to and can be any of the following:

debug: specifies that the template is for debugger files.
source: specifies that the template is for source files.
altsource: specifies that the template is for alternate source files. (An alternate source file refers to source code altered by a #line preprocessor statement that specifies a filename.)
systeminclude: specifies that the template is for system include files.
userinclude: specifies that the template is for user include files.

FORMAT DESCRIPTIONS

Format 1:

This format of the set command specifies a search list for the type of files designated by file-tag. A search list consists of one or more templates that are used by the debugger when it needs to locate debugger or source files.

The =| +| - argument is used as follows:

= sets the search list equal to the specified templates.

+ appends the specified templates to the search list.

- removes all occurrences of the specified templates from the search list.

The template arguments define the search list. Each template argument uses one or more of the following conversion specifiers to define a template used by the debugger to generate filenames:

%lower or %l: causes the replacement text for the conversion specifier immediately following the %lower to be converted to lowercase. The character after the %lower or %l must be the start of another conversion specifier.
%upper or %u: causes the replacement text for the conversion specifier immediately following the %upper to be converted to uppercase. The character after the %upper or %u must be the start of another conversion specifier.
%sname or %s: is replaced by the section name of the program being debugged. (The section name or SNAME should always be specified when the program is compiled.) The section name is always uppercase; if a lowercase version is required, prefix the %sname or %s specification with %lower.
%fullname: is replaced by the entire filename used by the compiler when it opened the file, including any SAS/C style prefix the compiler used. The format of the filename is operating system dependent. This conversion specifier may be difficult to use without a complete knowledge of SAS/C style prefixes and how the compiler derives specific file names. This conversion specifier is most useful for alternate source files, where it will be replaced by the complete filename that appears in the #line statement.
%leafname or %lf: is replaced by the portion of the filename after the last slash, if present. If there is no slash, it is the entire filename the compiler used to open the file.
%basename or %b: is replaced by the portion of %leafname that is before the last dot. If there is not a dot in %leafname, then %basename is the same as %leafname.
%extension or %e: is replaced by the portion of %leafname that is after the last dot. If there is not a dot in %leafname, then %extension is set to a null string.

You can include a percent character ( %) in a template by specifying two percent characters in a row ( %%).

The filenames generated by the application of the conversion specifiers in the template are passed to the fopen function, in an attempt to open the specified file.

For example, on MVS the following template would access a PDS member that matches %sname:

 "dsn:userid.proj4.h(%sname)"

A file in the POSIX-conforming hierarchical file system, as implemented by OpenEdition MVS, could be accessed by a template like this:

 "hfs:dbgfiledir/%leafname"

If %leafname consists of a base and an extension, a functionally equivalent template could be specified as follows:

 "hfs:dbgfiledir/%basename.%extension"

A similar template could be specified to access source files on CMS in the Shared File System, for example:

 "sf:%sname C fpool:userid.proj4"

Format 2:

The second form of the set search command is used to remove all of the search templates associated with a file-tag. It specifies a null search list.

Format 3:

The question mark ( ?) character is used to display the search list associated with a file-tag. An asterisk ( *) can be used as a wildcard character in place of a specific file-tag argument. Specifying set search * ? will display the search lists for all debugger and source files, including the cache location, if it was specified with a set cache command.

Format 4:

The last form of the set search subcommand is used to turn tracing on or off. When tracing is turned on, the debugger displays a message each time it attempts to open a file, possibly using a filename generated by a template. The message displays the name of the file the debugger was looking for and whether or not the search was successful.

An asterisk ( *) can be used as a wildcard character in place of a specific file-tag argument. If an asterisk is specified for the file-tag, tracing will be affected (either turned on or turned off) for all file types supported by set search.

cache SUBCOMMAND

The set cache command is used to specify a cache location for the debugger file. (In a cross-development environment, the original debugger file may be located on the UNIX workstation and the cache location will be on the target mainframe.) A cache location is specified to provide faster access to debugging information.

The format for the set cache subcommand is as follows:

Format:: set cache debug = " template "

Notice that debug is the only valid type of file for the set cache subcommand.

The template argument is described in the previous section and is used to specify the cache location. When debugging a program, the debugger first looks for the debugger file in the cache location. If the debugger finds a current version of the debugger file in the cache location, then the debugger uses that file. If a debugger file is not found in the cache location, or if the debugger file in the cache location is not current, then the current debugger file is copied to the cache location. However, if the cache file is not a valid debugger file, it will not be overwritten by the debugger.

EXAMPLES

set search userinclude = "path:/usr/c/headers/%leafname": specifies a search list for user include files. When the debugger looks for source code that was included from a user include file located on a UNIX workstation, this template is used to generate a filename and open the file on the workstation.
set search userinclude + "dsn:userid.c.headers(%basename)": specifies a template that is appended to the search list for user include files that was established in the previous example. This template generates an MVS dsn: style filename that is searched if the user include file is not found on the workstation.
set search source = "hfs:/home/cxx/src/%leafname": specifies a search list for sources files in the OpenEdition hierarchical file system. When the debugger looks for source code, this template is used to generate a filename and open the file.
set search userinclude trace on: turns tracing on for user include files. Whenever the debugger searches for a user include file, a message will be displayed telling you the name of the file searched for and if the search was successful or not.
set search userinclude ?: displays the search template list used to generate filenames for user include file searches.
set search userinclude =: resets the search template list for user include files to null.

SYSTEM DEPENDENCIES

The filenames generated by the search templates are operating system dependent.

COMMAND CAN BE ISSUED FROM

PROFILE yes

configuration file no

Source window prefix none

SCOPE

The set command is not affected by changes in scope.

RETURN CODES SET

Successful: 0

Unsuccessful: 1

Chapter Contents
Previous
Next
Top of Page

`=`	sets the search list equal to the specified templates.
`+`	appends the specified templates to the search list.
`-`	removes all occurrences of the specified templates from the search list.