@database "sc_util" Copyright (c) 1993-1995 SAS Institute, Inc, Cary, NC All Rights Reserved @master "sc_util.guide" @Remark $VER: sc_util.guide 6.55 (2.1.95) @Remark AmigaGuide database for the SAS/C Development System Utilities @Node Main "sc_util.guide" @{" cpr " Link "cpr"} CodePRobe - Source level debugger @{" cprk " Link "cprk"} CodePRobe - Cross-debugger kernel @{" cprx " Link "cprx"} CodePRobe - Cross-debugger version @{" cover " Link "cover"} Analyzes coverage data @{" demangle " Link "demangle"} Converts C names into C++ name @{" diff " Link "diff"} Determines the differences between two files @{" grep " Link "grep"} Searches for and prints regular expressions @{" gst " Link "gst"} Manages global symbol tables @{" guiprof " Link "guiprof"} Graphical code profiler @{" hypergst " Link "hypergst"} Displays the contents of GSTs @{" lctosc " Link "lctosc"} Converts older V5 options to newer options @{" lprof " Link "lprof"} Generates run-time statistics @{" lstat " Link "lstat"} Analyzes and prints run-time statistics @{" mkmk " link "mkmk"} Creates makefiles @{" omd " Link "omd"} Disassembles object modules @{" oml " Link "oml"} Manages libraries @{" sc " Link "sc"} SAS/C Development System driver @{" sc5 " Link "sc5"} SAS/C Development System V5 compatible driver @{" scmsg " Link "scmsg"} Searches for and corrects errors and warnings @{" scompare " link "scompare"} Generates patch files @{" scopts " Link "scopts"} Sets compiler options @{" scsetup " Link "scsetup"} Sets up a new project @{" slink " Link "slink"} SAS/C Development System Linker @{" smake " Link "smake"} Maintains and updates records of file dependencies @{" smfind " link "smfind"} Finds strings in text files @{" spatch " link "spatch"} Applies patches to files @{" splat " Link "splat"} Searches and replaces patterns matching regular expressions @{" sprof " link "sprof"} Determines the time a program spends in each function @{" tb " Link "tb"} Displays traceback information @EndNode @Node "cpr" cpr - CodePRobe - Source level debugger Synopsis cpr [@{" options " Link "cpr options"}] program [program parameters] Description CodePRobe is a powerful source-level debugger that enables you to monitor, line-by-line, the behavior of your C program, Assembler program, or both. See Also @{" cpr commands " Link "sc:help/cpr.guide/main"} , @{" cpr options " Link "cpr options"} @EndNode @Node "cpr options" -buffer size Specifies the size of the Dialog window buffer. By default, the Dialog window saves the last 4096 bytes displayed so that you can scroll backwards and review output. "size" is the new buffer size in bytes. -cli instructs CodeProbe to invoke your application as a Shell (CLI) process. CodeProbe passes arguments to the application through the normal command line interface. This option is the default if CodeProbe is invoked from a Shell. The option is necessary if CodeProbe is invoked from the Workbench screen, and you want your program to run as if invoked from a Shell. -command commands executes the specified debugger commands at startup. The commands are executed after go main if the -startup option is not specified or after the profile script if -startup is specified. For example, the command cpr -command "proceed; display fahr" program-name executes to main, steps over 1 line of code, and displays the variable fahr before giving control to you. -i sets up a screen in interlace mode. By default, CodeProbe opens a new screen using the specifications set up by Preferences for Workbench screens. To force a screen to be opened in interlace mode, include the -i option before typing the application command name. -line starts CodeProbe in line mode. See "Running CodeProbe in Line Mode," earlier in this chapter, for more information. -nommu tells CodeProbe not to use the MMU. This option is useful only if you have a 68020 or higher CPU. If your machine is running Enforcer and has a 68020 or higher CPU, CodeProbe tries to use the MMU to stop references to illegal memory. For these machines, specifying -nommu tells the debugger not to verify memory in the MMU tables before trying to access the memory. However, if Enforcer is running, you will still not be able to display illegal memory. -noprofile suppresses execution of the CodeProbe startup file. When CodeProbe is invoked, it automatically executes a script file named cprinit, which must be located in either the current directory or ENV:sc. If the startup file is in the current directory, CodeProbe does not search ENV:sc. -screen screen-name tells CodeProbe to open its windows on the named public screen. By default, CodeProbe creates a new public screen named SC_CPR.1 when it is invoked. If you specify -screen, CodeProbe looks for an existing public screen with the specified name, and if it finds one, CodeProbe uses that screen to display its windows. If a screen with the given name does not exist, CodeProbe creates a new one with that name. To use the Workbench screen, specify -screen workbench. Public screens are a feature of Intuition 2.0. For users of earlier versions of Intuition, this option is not generally useful. However, specifying -screen workbench causes CodeProbe to use the Workbench screen on older releases. -startup suppresses the automatic go main that is normally executed by the debugger on startup. This option is useful you want to step through the startup code or debug constructors or autoinitialization functions that run before main. If you specify -startup, the application process does not perform any type of initialization before control is given to you. If the quit, start, or restart commands are invoked and an application process has not exited, the debugger normally calls exit to clean up any process resources that may not have been freed. However, if you invoked CodeProbe with the -startup option, exit is not called. -w runs CodeProbe on the Workbench screen. Specifying -w is equivalent to specifying -screen workbench. -wb tells CodeProbe to invoke the application as a Workbench process. It passes arguments to the application through a Workbench startup message. This option is the default if CodeProbe is invoked from the Debug icon. The option is necessary if CodeProbe is invoked from a Shell, but you want the application to run as if invoked from the Workbench screen. -wdialog left top width height -wregister left top width height -wsource left top width height -wwatch left top width height specifies startup window coordinates for the Dialog, Register, Source, and Watch windows, respectively. Window coordinates are measured in character positions. A width or height of 0 causes the window to extend to the screen border on the right or bottom, respectively. For example, to open the Source window in position (0,1) and make the Source window 50 characters (columns) wide and 12 lines long, you would specify: cpr -ws 0 1 50 12 program-name NOTE: The Register and Watch windows are not displayed on startup. However, when they are opened by pressing the appropriate function key (either F1 or F4), they will open to the coordinates specified on the command line. -. suppresses the copyright banner that is displayed at startup. @EndNode @Node "cprk" cprk - CodePRobe - Cross-debugger kernel Synopsis cprk [option] Description This kernel program is a version of CodePRobe, a powerful source-level debugger that enables you to monitor, line-by-line, the behavior of your C program, Assembler program, or both. This version is to be run on a machine which will be debugged remotely, via the @{" cprx " Link "cprx"} program. cprk supports the following communication parameters: -pipe name specifies that a named pipe is to be used instead of the serial port. If name is not specified, pipe:cpr is used. CPRX or CPRK will open two pipes using name as a base, name_d and name_k. To communicate successfully over a network, you must invoke either CPRX or CPRK with a pipe filename that refers to a pipe on the other machine. If your network allows you to refer to a pipe device on an attached machine by specifying net:pipe/pipename then you can start CPRK on the target machine using cprk -pipe net:pipe/cpr and start CPRX on the host machine with the -pipe option without a pipename. -device name specifies that the named device should be opened for communications if -pipe was not specified. The default is serial.device. -unit number specifies the unit number of the communications device if -pipe was not specified. The default is zero (0). -speed number specifies the baud rate of the communications device if -pipe was not specified. The default is the value is set with the Serial editor in the Prefs drawer from Workbench. See Also @{" cprx " Link "cprx"} @EndNode @Node "cprx" cprx - CodePRobe - Cross-debugger version Synopsis cprx [@{" options " Link "cprx options"}] program [program parameters] Description This is the Cross-Debugger version of CodePRobe, a powerful source-level debugger that enables you to monitor, line-by-line, the behavior of your C program, Assembler program, or both. This version of cpr allows you to control a program running under the @{" cprk " Link "cprk"} kernel program on another machine, via a serial or NetWork link. See Also @{" cprx commands " Link "cprx commands"} , @{" cprk " Link "cprk"} , @{" cprx options " Link "cprx options"} @EndNode @Node "cprx commands" In addition to all regular @{" cpr commands " Link "sc:help/cpr.guide/main"}, cprx also recognises the following: finish The program being debugged is automatically terminated if it has not yet completed execution. quit CPRK continues running, so you can start another CPRX session. The program being debugged is automatically terminated if it has not yet completed execution. @EndNode @Node "cprx options" In addition to all regular @{" cpr options " Link "cpr options"}, cprx also recognises the following: -pipe name specifies that a named pipe is to be used instead of the serial port. If name is not specified, pipe:cpr is used. CPRX or CPRK will open two pipes using name as a base, name_d and name_k. To communicate successfully over a network, you must invoke either CPRX or CPRK with a pipe filename that refers to a pipe on the other machine. If your network allows you to refer to a pipe device on an attached machine by specifying net:pipe/pipename then you can start CPRK on the target machine using cprk -pipe net:pipe/cpr and start CPRX on the host machine with the -pipe option without a pipename. -device name specifies that the named device should be opened for communications if -pipe was not specified. The default is serial.device. -unit number specifies the unit number of the communications device if -pipe was not specified. The default is zero (0). -speed number specifies the baud rate of the communications device if -pipe was not specified. The default is the value is set with the Serial editor in the Prefs drawer from Workbench. -symfile filename specifies the location of the executable file on the host machine. If the executable file is located in different places on the target and host, then use this option, to specify where the executable file resides on the host machine. CPRK still looks in the location specified by target-executable-filename. -x strips all debugging information from the host's version of the executable file, copies the stripped version to the target machine, and tells CPRK to invoke the just-transmitted version. This option allows CPRK to run constantly without changing disks or rebooting (as long as your program does not crash). @EndNode @Node "cover" cover - Analyzes coverage data Synopsis cover [@{" options " Link "cover options"}] [datafile]. . . Description The cover utility analyzes the coverage data produced when you compile your program with the COVERAGE option, link with the object file covutil.o, and run your program. Using this data, you can determine which lines of code in your program were executed and which were not. This information can help you design test cases that exercise all paths through your program. See Also @{" cover options " Link "cover options"} @EndNode @Node "cover options" dir=directory-pathname specifies the directory path or paths to search to locate the C source files. merge filename tells cover to read the specified data files, merge the information contained in them, and write the merged data to filename. nosource tells cover not to read in the C source files. @EndNode @Node "demangle" demangle - Converts C names into C++ names Synopsis demangle C-name C-name... Description The demangle utility converts the specified C names that were generated by the C++ translator into their original C++ forms. If you run sc with the cxxonly option, the resulting ..c file contains C names that were generated by the translator. To read this file, you may need to use the demangle utility to convert the C names. If you compiled with the debug option, the debugging information in the object module refers to the names generated by the translator. In many cases, the debugger can also display the C++ name. If you want to run the debugger from an AREXX script, you may need to use demangle to convert the C names. Example > demangle bar__3foo foo::bar bar__3foo is the mangled C name as it would appear in the generated ..c file. foo::bar is the demangled C++ name as it would appear in your C++ source file. @EndNode @Node "diff" diff - Determines the differences between two files Synopsis diff [>destination] [@{" options " Link "diff options"}] file1 file2 Description The diff utility determines the differences in contents between two files and describes the lines that you should delete from, add to, or change in file2 to make it look like file1. To help you find those lines, diff identifies the line numbers and gives the text of the lines. If you enter the diff command without specifying filenames, diff displays the version that you are using and describes the options available. Output from this utility is sent to the standard output device, unless you redirect it by specifying the -o option or by entering a greater than (>) sign followed by a destination. NOTE: Appendix 1, "diff File-Matching Algorithm," discusses the theory of file matching and how it affects diff. See Also @{" diff error messages " Link "diff error messages"} , @{" diff options " Link "diff options"} @EndNode @Node "diff options" -bnn sets the size of the I/O buffer to the value specified by nn. The default I/O buffer size is 4K, and the maximum size is limited by the amount of available system memory. -c displays only those lines common to both files. -Fnn sets the column number where you want diff to begin comparing lines. For example, if you set nn to 25, diff ignores the first 25 characters on each line. -Lnn sets the column number where you want diff to stop comparing lines. For example, if you set nn to 75, diff ignores the characters beyond column 75 on each line. -lnn defines the number of lines, nn, per file that can be handled by diff. diff uses two tables (one for each file) to keep track of the lines read in from each file. The default size of each of these tables is 2000; the maximum number is limited by memory availability. -ofile sends the output to the specified file (or device). You can use this option instead of the AmigaDOS redirection command. You can send the output to a different device by specifying the device name. For example, to send output to the printer, specify -oprt:. To send output to a file on drive df0:, specify -odf0:filename. -p filters out unprintable characters from the input stream. You can use this option to clean out an AmigaDOS binary file. -q suppresses any messages if there are no differences between the specified files. -w ignores differences related solely to space or tab characters and reduces sequences of these characters to a single space. This option also removes trailing blanks. When you specify the -w option, diff uses additional memory to create a third table for each line in its compressed form. @EndNode @Node "diff error messages" Can't open file indicates that diff cannot open the named file. The file may not exist or it may be protected. Diff I/O Error indicates an I/O problem. Improper -l specification: nn indicates that diff cannot interpret the nn value specified with the -l option as a number. Internal Error: ... indicates an internal error. Please contact the Technical Support Division at SAS Institute if you see this error message. The Technical Support representative will need the following information: > the version of diff you are using > the exact wording of the command line you used > the exact wording of the message you received > the size of the files you were trying to compare. Line table overflow indicates that one of the two line tables, in which diff stores the lines from each file while they are being compared, is too small to hold the lines in one of the files. Try increasing the line table size with the -l option. Not enough memory for nn lines per file indicates that you have used the -l option to increase the line table size, but you do not have enough memory to increase it by the amount you specified. Out of memory indicates that diff is out of memory. Try decreasing the line table size with the -l option if possible. Do not use the -w option. You can also try decreasing the size of the I/O buffer by using the -b option; however, this action makes diff run slower because more disk accesses may be required. If you are using a hard disk, this factor may be negligible. Too many file names: ... indicates that you have made an error on the command line in such a way that diff assumes you are attempting to operate on more than two files. Unrecognized option indicates that you specified an option that diff does not recognize. @EndNode @Node "grep" grep - Searches for and prints regular expressions Synopsis grep [>destination] [@{" options " Link "grep options"}] pattern file . . . Description The grep utility searches the files you specify for all the lines that contain the specified pattern. For each file in which it finds the pattern, grep displays, on the screen, the filename, line number, and contents of the line that contains the matching string. The patterns that you can specify can be specific or general, and they are sometimes referred to as regular expressions. In this text, they are referred to as patterns. To specify the files that you want grep to search, you can use the AmigaDOS wildcards (eg. #?). Specifying the Pattern The following list describes the special characters that you can use to specify the pattern for which you are looking: . is the grep wildcard character. A period will match any single character, including a space, tab, newline, or control character. A period followed by an asterisk (*) tells grep that any number of any characters can be present. The .* sequence is equivalent to the #? sequence for AmigaDOS commands. "" are used to enclose patterns that include space characters. [ ] are used to search for any one character from a set of characters by enclosing that set of characters inside square brackets. A set of characters enclosed in square brackets is called a character class. A character class will match one single character. For example, to search for lines that contain vowels, you can enter [aeiou]. n(--) - is used to specify a range. Inside a character class, you can specify a range of characters by entering the first character in the range and the last character in the range separated by a hyphen. The first character must occur alphabetically before the second. For example, to find any one of the lowercase alphabetic characters, you enter [a-z]. ! is used as the negation character when included as the first character in a character class. An exclamation point tells grep to find any character that is not in the character class. For example, to find any one character that is not a lowercase alphabetic character, enter [!a-z]. To find any one character that is not a lowercase alphabetic character and is not the end-of-line character, enter [!a-z\N]. * tells grep that the preceding character does not have to be present in the pattern but can be present an unlimited number of times. In other words, an asterisk means "zero or more occurances of." A period followed by an asterisk tells grep that any number of any characters can be present. The .* sequence is equivalent to the #? sequence for AmigaDOS commands. NOTE: Following AmigaDOS conventions, if the * is used inside quotes, it is treated as an escape character, so will need to be doubled to actually pass a * to grep. In other words, if the search string is "foo* bar", you will need to type "foo** bar" instead. + tells grep that the preceding character must be present in the pattern at least one time but can be present an unlimited number of times. In other words, a plus sign means "one or more of." For example, to find all lines in your file that contain one or more of the lowercase letter t, enter t+. ^ tells grep that the pattern must begin in column 0. Enter the caret (^) at the beginning of the pattern. grep will look only for those lines in which the pattern occurs beginning in column 0. For example, to find all lines that begin with a left parenthesis, enter ^(. $ tells grep that the pattern must occur at the end of a line. Enter the dollar sign at the end of the pattern. For example, to find all lines that end with a right parenthesis, enter )$. \ is the escape character. If you want to search for any of the special characters included in this list, you must enter a backslash before that character. For example, to find all lines that contain a caret, enter \^. Similarly, if you want to search for a backslash, enter two backslashes, \\. You also need to use the backslash to identify certain additional characters. These characters are as follows: \b backspace \n newline \r carriage return \s space \t tab \xij control character identified by hexadecimal digits ij For example, to locate all lines containing the Control-g character, enter \x07. See Also @{" grep error messages " Link "grep error messages"}, @{" grep options " Link "grep options"} @EndNode @Node "grep options" -c prints the total number of matched lines. -f prints only the names of all files in which grep finds a string that matches the pattern. -n tells grep not to display line numbers. -p displays only printable ASCII characters. Non-printable characters are filtered out. This option is useful if you are searching a binary file that may contain control characters. -q does not display filenames or line numbers. -s displays the names of all files that grep searches. Normally, grep displays only those filenames in which it found a match for the pattern. -v prints only the lines in which a match of the pattern is not found. -V prints the version number of grep. -$ tells grep not to distinguish between upper- and lowercase. For example, if you use this option, the pattern int would match int, INT, Int, and INt. @EndNode @Node "grep error messages" Bad character class indicates that grep is unable to interpret a character class in the pattern you have asked it to find. Check to see if you have used any special symbols that you did not intend to use. This message also can be generated if, in specifying a character class and using the minus (-) character to indicate a range of characters, the first character in the range does not alphabetically precede the second (for example, [d-a]). Bad pattern indicates that grep is unable to interpret the pattern you are asking it to find. You may have used a special character in the pattern that does not make sense in this context. Check to see if you have forgotten to escape a special character. Can't find file(s) ... indicates that grep is unable to find one or more of the files you have asked it to search. The files may not exist, or you may have misspelled the filenames. Can't open ... indicates that grep is unable to open the named file. The file may not exist or may be protected. Closing ] not found indicates that grep believes that you have asked it to search for a pattern that contains a character class, but you have omitted the right bracket (]) that terminates the character class. If not, you may have included a left bracket ([) in the pattern but forgot to use a backslash (\) before it. Empty character class indicates that a character class you have used in your pattern has no members, for example [ ]. Improper hex specification indicates that you have used the x escape sequence but have not followed it with two recognizable hexadecimal digits. Incompatible combination of options indicates that the options with which you have invoked grep are contradictory. Internal Error: ... indicates an internal error. Please contact the Technical Support Division at SAS Institute if you see this message. The Technical Support representative will need the following information: > the version number of grep you are using > the exact wording of the command line you used > the exact wording of the resulting error message. Invalid option indicates that you have used a command line option that grep does not recognize. This message also can be generated if your pattern begins with a minus sign (-) but you have not escaped it or enclosed the pattern in double quote marks ("). No beginning double quote in pattern indicates that grep has detected double quote marks (") in a pattern that did not start with a double quote. You may need a backslash (\) before the double quote. No file arguments provided indicates that grep believes you have specified a pattern but no filenames. This message also may be generated if you invoke grep with a filename but no pattern. No pattern or file arguments given indicates that grep cannot find either a pattern or filename on its command line. Out of space indicates that grep has run out of space in constructing its pattern representation. Please contact the Technical Support Division at SAS Institute if you see this message. Pattern ill-formed: no terminating double quote indicates that you started the pattern with a double quote (") but failed to terminate it with one. Too few arguments to GREP indicates that grep demands at least two arguments on its command line: a pattern and at least one filename. @EndNode @Node "gst" gst - Manages global symbol tables Synopsis gst [gst-filename] [@{" options " Link "gst options"}] [symbol-name . . . ] Description A Global Symbol Table (GST) is a collection of all the information defined in a set of header files and stored in a format that the compiler can use easily and quickly. For information on creating and using GSTs, refer to Chapter 4, "Using the System Header Files to Access Libraries," in SAS/C Development System Library Reference. The gst utility helps you manage GSTs and extract information from a GST. To load a GST into memory, specify the GST command as follows: gst gst-filename The gst utility loads the GST into memory and then exits. NOTE: You should do this only if you plan to remove the disk containing the GST from the drive. To display information about a symbol contained in a GST, specify the gst command as follows: gst gst-filename symbol-name Some symbols may occur more than once in the GST. For example, a symbol may occur once as a structure tag and again as an identifier. The gst utility prints all definitions of the same symbol. See Also @{" gst error messages " Link "gst error messages"}, @{" gst options " Link "gst options"} @EndNode @Node "gst options" list lists all GSTs currently in memory. You can use this option to determine which GSTs to unload if you need more memory. [name=]filename specifies a GST file created using the makegst option in the sc command. You do not need to specify name= unless you want to load a GST that has the same name as a keyword (for example, name=symbol). If you use the special name anygst, the gst utility uses the first GST on its list, as reported by gst list. [symbol=]symbol-name displays the type of symbol name and the filename and line number where symbol-name is defined. The type may be one of the following: n(Preprocessor) tag struct, union, or enum name identifier variable or function name typedef typedef include #include filename preprocessor preprocessor macro or #define You do not need to specify symbol= unless you want information about a symbol that has the same name as a keyword (name, unload, and so on). unload forces a GST to be unloaded from memory. If you also specify symbol names on the command line, gst prints all definitions for those symbols before it unloads the GST. verbose prints the full definition of symbol-name. @EndNode @Node "gst error messages" No GST file specified indicates that you did not specify a GST filename. Can't find GST file "filename" indicates that gst cannot find the file specified. Symbol "symbol-name" not found indicates that gst could not find the specified symbol. Not enough memory to load GST indicates that the GST file could not be loaded due to insufficient memory. @EndNode @Node "hypergst" hypergst - Displays the contents of GSTs Synopsis hypergst [gst-filename] Description The hypergst utility allows you to browse the definitions of symbols and data structures in GSTs (Global Symbol Tables) that are loaded into memory. hypergst works with the AmigaGuide hypertext system. For information on using AmigaGuide, see Chapter 2, "Getting Help," in SAS/C Development System User's Guide, Volume I: Introduction, Editor, Compiler. To browse the definitions in a GST, the GST must be loaded in memory. You can invoke the hypergst utility and load a GST in one of two ways: > You can enter the hypergst command followed by the name of the GST file that you want to browse. > From the Workbench, you can click on the HyperGST icon, then hold down the Shift key and double-click on the icon for the GST file that you want to browse. If the GST that you want to browse is already loaded into memory: > You can enter the hypergst command without specifying a GST filename. hypergst displays a screen listing the names of all GSTs in memory. To select a specific GST, click on the name of the GST file. > You can double-click on the HyperGST icon. hypergst displays a screen listing the names of all GSTs in memory. To select a specific GST, click on the name of the GST file. After the GST is loaded, hypergst displays a screen containing buttons for the various kinds of symbols defined in the GST. These buttons are as follows: > Data Items > Prototypes > Typedefs > Structs/Unions/Enums > Preprocessor Symbols If you click on one of these buttons, hypergst displays an alphabetical list of all symbols of that type in the GST. If you click on the name of a symbol, hypergst displays a symbol information screen for that symbol. This screen may contain other buttons that reference header files, structure tags, type definitions, and so on. You can click on any of these buttons to display more information about the highlighted item. See Also @{" hypergst error messages " Link "hypergst error messages"} @EndNode @Node "hypergst error messages" No GST files in memory indicates that you have not loaded any GST files into memory. For example, you see this message if you invoke hypergst immediately following a reboot and do not specify any arguments. @EndNode @Node "lctosc" lctosc - Converts older V5 options to newer options Synopsis lctosc [>file] [lc options] Description This utility will convert V5 'LC' options to the newer 'SC' option style. It prints the converted options to stdout. To keep and use these converted options, you will need to redirect the output of lctosc to a file using the AmigaDOS '>' output redirection operator. The new driver looks for options in a file named "SCOptions". You may either type the options to be converted on the command line, or redirect the input to lctosc from a file using the AmigaDOS '<' input redirection operator. The old driver, LC, looked for options in a file named "SASCOPTS". @EndNode @Node "lprof" lprof - Generates run-time statistics Synopsis lprof [-t=n] [>prog-output-dest] program [program-options] Description The lprof utility generates run-time statistics for a program. lprof records the amount of time spent in each routine that is called as your program runs. To use lprof with your program, you must compile your program with the debug option. After lprof loads your program, it runs the program and gathers statistics by examining the current program counter at given intervals. lprof writes your program's statistics to the file named prof.out in the current directory. You can use the lstat utility to produce a report from those statistics. lprof only supports one option: -t=n specify the interval, in milliseconds, between lprof statistics checks on your program. See Also @{" lstat " Link "lstat"} @EndNode @Node "lstat" lstat - Analyzes and prints run-time statistics Synopsis lstat [>destination] [@{" options " Link "lstat options"}] program [profile] Description The lstat utility analyzes the profile statistics created by @{" lprof " Link "lprof"}. The profile is the name of the output file created by lprof. lstat first looks in your current directory for the default file produced by lprof, prof.out. If this file is not in your current directory, or if you have changed its name, you must specify its full pathname as the value for profile. You must specify the program name. lstat uses this name to get debugging and symbol information for its report. NOTE: This utility assumes that you have linked the program with the addsym linker option. The addsym linker option allows the profiler to produce statistics for library functions. If you link your program using the link and debug options in the sc command, the linker automatically links your program with the addsym option. If you are linking with a separate slink command, you must specify the addsym linker option. If the report produced by lstat shows that a large percentage of time is spent in one program module, you may want to > redesign the module > incorporate the module into the calling routines, thus eliminating calling overhead > rewrite the routine in assembly language > restructure your program. You also may find that most of the work being done involves the routine in question, and the percentage of time taken is reasonable. See Also @{" options " Link "lstat options"} @EndNode @Node "lstat options" -z tells lstat to display statistics for all subroutines even if they were not encountered in profiling. By default, lstat does not report subroutines that it does not encounter. -f tells lstat to display full statistics for each subroutine, indicating the line numbers within a module that it encountered. By default, lstat displays only summary information about the subroutine. -t=n tells lstat to display only those routines that have at least n hits. By default, lstat prints all subroutines that it encountered even once. @EndNode @node "mkmk" mkmk - Creates makefiles Synopsis mkmk [options] [filename...] Description The mkmk utility creates makefiles. mkmk examines the source and header files you specify, determines which files depend on which other files, and generates a makefile. If you do not specify any filenames, mkmk examines all the files in the current directory ending with .c, .cxx, .cpp, or .cc. mkmk supports the following options: target=filename specifies the name to use in the makefile for the target executable module. If not specified, the root part of the name of the first .c, .cxx, .cpp, or .cc file in the file list is used. force tells mkmk to overwrite an existing makefile. makefile=filename tells mkmk to write the makefile to the specified filename. The default filename is smakefile. After running mkmk, you can build your project by entering smake from the Shell or by double-clicking the Build icon from the Workbench. If you add any new files to your project, or if you add or delete any #include directives in existing files, you need to add them to the generated makefile either by editing the makefile or by rerunning mkmk. The source code for mkmk is in the sc:extras/mkmk directory. @endnode @Node "omd" omd - Disassembles object modules Synopsis omd [>destination] [-x] object [source] Description The omd (Object Module Disassembler) utility program disassembles an object file produced by the SAS/C Compiler and produces a listing consisting of assembly language statements (interspersed with the original C source code if you specified a source filename). object is the object filename. You must specify the complete filename, including the .o extension. source is the source filename. If you specify source, you must specify the complete source filename, and the source file should have been compiled with the debug compiler option. The debug option allows omd to associate source lines with the object code they generated. If you did not use the debug option, C source lines will not appear in the output produced by omd. omd only supports one option: -x This option sets the size of the buffer used to hold the external symbol section of the object module. For example, -x250 establishes a buffer that can hold 250 external symbols. The default size is 200. You should increase the buffer size only if omd reports that there are too many external symbols. @EndNode @Node "oml" oml - Manages libraries Synopsis oml [listfile] [@{" options " Link "oml options"}] libfile [command [module. . . ]]. . Description You can use the oml (Object Module Librarian) to manage your libraries. oml allows you to: > create library files > list the modules in a library file > delete modules from a library file > replace old modules with new modules. A link library is a group of object modules, each of which was originally in a separate file and consisted of one or more subroutines. Some advantages of using a link library are as follows: > The subroutines in a library can be used by several programs. > When you are linking your program, you specify only the library file instead of several individual object modules. > The linker includes only those modules in the library that are required by your program. Each module within the library is identified by a module name, which is placed in the object module by the program (the SAS/C Assembler or Compiler) that generates the module. The assembler and compiler use the name of the object file. If a module does not contain a module name, oml assigns a module name of the form $nnn, where nnn is a decimal number. A module may define one or more public symbols. A public symbol is something in the module that is available to other modules, such as global variables or functions. When the linker resolves external references for a program, it examines each module in each library you specify. It decides which of the modules are required by the program it is linking by looking at the module's list of public symbols. If any of the program's unresolved external references match any of the module's public symbols, that module will be included in the executable module. When writing the modules for your library, be careful to avoid duplicate names for public symbols. If you create a library that defines a symbol more than once, oml issues a warning message. If you then link with that library without correcting the problem, the linker may include the wrong module or give a duplicate symbol error. To invoke oml, enter the oml command followed by a library name, as follows: oml mylib.lib oml waits for you to enter commands (and module names, if necessary) from the keyboard. oml executes the commands as you enter them and displays a list of any duplicate symbol names that it finds. After you have entered all your commands, enter a Control-backslash (Control-\) to terminate oml. You also can include the commands and module names on the oml command line. If you enter commands on the command line, oml executes those commands and terminates. For example, the following command replaces the module ftoc.o in mylib.lib with the version of the same module in your current directory: oml mylib.lib r ftoc.o oml replaces the module, lists any duplicate symbol names it finds, and terminates. You also can enter some commands on the command line followed by some from the keyboard. If you include an at (@) sign at the end of the command line, oml executes the commands you enter on the command line and then waits for you to enter additional commands from the keyboard. You must enter a Control-\ to terminate oml. For example, the following command replaces the module ftoc.o in mylib.lib with the version of the same module in your current directory and then waits for you to enter additional commands from the keyboard: oml mylib.lib r ftoc.o @ You also can enter the commands into a file and tell oml to use that file as input. You can tell oml to use that file by either of the following methods: > entering a less than (<) sign followed by the filename ( entering an at (@) sign followed by the filename (@cmdfile) as the last item on the oml command line. oml sends its output to the screen unless you redirect it by specifying a greater than (>) sign followed by a filename. oml produces warning messages if either of the following are true: > A module that you want to delete or extract is not in the library. > Any module in the library includes a second definition for a public symbol. See Also @{" oml commands " Link "oml commands"} , @{" oml options " Link "oml options"} @EndNode @Node "oml commands" r file file ... replaces the named object files in the library or adds them to the library, if they are not already present. Each module should be in a separate object file. To replace modules within a library, make sure that the module contains a module name and that the filename is the same as the module name. d module module ... deletes the named modules from the library. oml assigns module names to those modules without names; therefore, you may need to get a listing of names in the library (using the l command) to determine the name of the module that you want to delete. x module module ... extracts the named modules from the library and creates separate files using the same names. You may need to get a listing of names in the library (using the l command) to determine the correct name of the module that you want to extract. If the module name contains a pathname, oml attempts to create a file with that name. If the module name does not contain a pathname, oml creates the file in the current directory unless you specify a different pathname with the -o option. You can use an asterisk (*) to specify that you want all modules extracted. oml terminates if it cannot extract a module. You cannot extract and replace the same module with the same oml command line. l generates a listing of the modules in the library after all other commands have been executed. If you also specify the -s option, the listing includes the public symbols defined in each module. \@[filename] tells oml to execute the commands that you enter from stdin (usually defined as the keyboard) or from the filename, if specified. If you include this option it should be the last option on the command line. @EndNode @Node "oml options" -b tells oml not to issue prompts, including prompts for missing information. -n strips debugging information from modules before adding them to the library. -oprefix specifies a prefix for the filenames to be created by the x command. If the prefix includes a directory name, you must include the forward slash (/) at the end of the name. -s includes, in the listing produced by the l command, a list of the public symbols defined in the module. -tpathname specifies a path for the temporary library. -v tells oml to display messages as it adds or deletes modules to and from the library. -x generates a cross reference for variables and functions used in a library. @EndNode @Node "sc" sc - SAS/C Development System driver Synopsis sc [@{" options " Link "sc:help/sc.guide/main"}] [source-filename(s)] Description This is the main command used to invoke the SAS/C Compiler. It manages loading the different parts of the compiler, and generating the output based on the options you specify on the command line, and/or in an SCOptions file. The sc command accepts C source files, assembly source files, object files, and link libraries as input files. See Also @{" sc options " Link "sc:help/sc.guide/main"} @EndNode @Node "sc5" sc5 - SAS/C Development System V5.10 compatible driver Synopsis sc5 [options] [source-filename(s)] Description This version of the SC driver is provided for compatibility with older versions of the SAS/C Compiler. It accepts the old-style options (such as -L, -cs, etc.). See the documentation for a version of SAS/C prior to V6 for details on the available options. See Also @{" sc " Link "sc"} @EndNode @Node "scmsg" scmsg - Searches for and corrects errors and warnings Synopsis scmsg [@{" options " Link "scmsg options"}] Description The scmsg utility helps you find and fix errors and warnings in your code. It acts as a filter between you and the compiler, allowing you to invoke the editor of your choice and go to the line causing the error or warning quickly and easily. To use scmsg, you must compile your program with the errorrexx option. You can use scmsg with the editor of your choice, using AREXX as a communication medium. AREXX is a standard part of AmigaDOS 2.0 and can be purchased as a third-party product for use under AmigaDOS 1.3. If you do not have AREXX, you still can use scmsg to control the se editor provided as part of the SAS/C Development System, but you will not be able to program the editor keys to control scmsg. If you invoke the compiler from the Shell or by using the Build icon on the Workbench, scmsg is automatically invoked for you. The current message is always highlighted. You can move from message to message by clicking on the message or by using the arrow keys. The scroll bar on the right side of the window allows you to move around in the list. Double-clicking on a message invokes the editor at the file and line number specified in the message. Every time a C source file is compiled, all old messages listing that file as the primary file are deleted from the scmsg window. See Also @{" scmsg AREXX commands " Link "scmsg AREXX commands"} , @{" scmsg options " Link "scmsg options"} @EndNode @Node "scmsg AREXX commands" Note: The AREXX Port name for scmsg is "SC_SCMSG". abort aborts any builds currently running. altfile returns the alternate filename (if any). An empty string indicates that there are no messages on the list or that the current message has no alternate file. altline returns the alternate line number (if any). An empty string indicates that there are no messages on the list or that the current message has no alternate file. bottom goes to the last message in the list. build [options] calls the smake utility, using the options specified, to rebuild the last project built. class returns either error or warning, depending on the current message. clear deletes all messages. delcomp [filename] deletes all messages with the specified filename as their primary filename. If no filename is specified, the primary filename of the current message is used. If the current message is deleted, the next non-deleted message becomes current. delete deletes the current message and goes to the next message in the list. delfile [filename] deletes all messages with the specified filename as their secondary filename. If no filename is specified, the secondary filename of the current message is used. If the current message is deleted, the next non-deleted message becomes current. delnum [msgno] deletes all messages with the specified message number. If no message number is specified, the number of the current message is used. If the current message is deleted, the next non-deleted message becomes current. file returns the filename for the current message. An empty string indicates there are no messages on the list. number returns the error number. An empty string indicates that there are no messages on the list. hide