Chapter Contents

Previous

Next
Cross-Debugging

set Command Reference

The SAS/C Debugger's set command is best used in the debugger PROFILE 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 the 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 search templates that are used to access debugger and source files, and 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.

The set search and set cache subcommands are described in the following paragraphs.


search SUBCOMMAND

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

search Subcommand Formats
Format Example
1 set search file-tag =|+|- "template1" ["template2" ...]
2 set search file-tag =
3 set search file-tag |* ?
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:

file-tag Values
Type of file Description
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 1: This format of the set command specifies a search list for the type of files designated by file-tag. Each search list consists of one or more templates that are used by the debugger to locate debugger or source file types.

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

set command Operations
Argument Description
= 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:

template Arguments
Value Description
%lower or %l
causes the replacement text for the conversion specifier 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 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 must have been specified when the program was 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 stored in the object or debugger files. The format of the filename is implementation dependent and this conversion specifier should not be used unless you have complete knowledge of the filename stored in the object or debugger files. 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 stored in the object or debugger files after the last slash, if present. If there is no slash, it is the entire filename stored in the object or debugger files.
%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.
%m
is replaced by the member name of the original source file if it was a member of PDS.

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

The filenames generated by the application of the conversion specifiers in the template are passed to the fopen function, which opens the appropriate file for the debugger to access. If these files are located on a remote host, the SAS/C Connectivity Support Library is used to establish an NFS connection between the local and remote host.

For example, to use SAS/C Connectivity Support Library to access files on a UNIX workstation, the following template could be specified:

"path:dbgfiledir/%leafname"

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

"path:dbgfiledir/%basename.%extension"

A similar template could be specified to access files on MVS. For example, the following template would access a PDS member that matches %basename :

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

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 final 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 debug, source, altsource, systeminclude, and userinclude files.

Reattempting a set search

Release 6.50 of the SAS/C Debugger enhances the set search capability introduced in Release 6.00. In Release 6.00, only one attempt to locate the debugger or source files would be made. This meant that if the set search commands located in the profile were not correct, or had not been corrected before an attempt to load the source, the current debugging session would have to continue without access to that particular source.

In Release 6.50, if a set search command is issued, followed by a list command, the debugger attempts to load any files that were not previously found, using the modified set search templates. For example, if an attempt to load a source file fails because the source files have been moved to the dataset SASC.APPL.SOURCE, issuing the command :

set search source+"dsn:sasc.appl.source(%basename)"

followed by a list command causes the debugger to reattempt the search for the source.

The set search issued does not have to directly correlate to the failed search. For example, a common problem encountered when debugging, is to forget to allocate the DBGLIB dataset definition. When the debugger fails to locate the debugger file, a command such as:

system alloc fi(dglib) dsn(appl.dbglib)shr

could be issued to allocate the DD. A `dummy' set search command could then be issued. For example:

set search altsource+""

followed by a list command will cause the search to be reattempted.

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 host 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 the 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 host workstation, this template is used to generate a filename and open the file on the workstation.

set search source =
   "hfs:/home/cxx/src/%leafname"

specifies a search list for source files in the OS/390 UNIX System Services hierarchical file system (HFS). The hfs: filename style prefix instructs the debugger to look for the file in the HFS file system and open the file if it is found.

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 OS/390 dsn: style filename that is searched if the user include file is not found on the workstation.

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.

set cache debug = "dsn:userid.cache.db(%sname)"

specifies an OS/390 data set used to cache the debugger file on the target mainframe.

set cache debug = "cms:%sname dbg370"

specifies the location of a CMS file used to cache the debugger file on a target mainframe.

SYSTEM DEPENDENCIES

The filenames generated by the search templates are dependent upon the names the compiler used to open the files originally, which are operating system dependent.

COMMAND CAN BE ISSUED FROM

debugger start-up file yes
command line 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

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.