Chapter Contents

Previous

Next
Command Directory

set

Control file access

ABBREVIATION
se{t}

FORMAT
set SUBCOMMAND SUBCOMMAND-ARGUMENTS

DESCRIPTION
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

The set command has two subcommands: search and cache . The set search subcommand is used to control the search templates that are used to access debugger and source files, and the set cache subcommand is used to specify a cache location for debugger files. The set cache subcommand 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, and 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 .
%member or %m specifies the member name of a partitioned data set.
%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 the 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 OS/390. 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 subcommand 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 subcommand.

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.

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 subcommand and set cache subcommand.

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:

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


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 subcommand.

The set search sub command is used to specify filename templates. Filename templates are used to 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 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 it 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 this 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 UNIX System Services shell, the filename string is interpreted as an OS/390 filename, not as a POSIX filename. If you want to specify searching for a file in the UNIX System Services hierarchical file system, you must begin the filename with the hfs: filename style prefix.  [cautionend]

Reattempting a set search
If a set search subcommand 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 data set 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 correlate directly to the failed search. For example, a common problem encountered when debugging, is to forget to allocate the DBGLIB data set 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 Data Definition (DD) statement. A "dummy" set search subcommand could then be issued. For example, the following command is followed by a list command that will cause the search to be reattempted:
set search altsource+""

cache SUBCOMMAND
The set cache subcommand 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 was 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 that are 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.