1 12/22/80 profile, pf
2
3 Syntax: pf program_names -control_args
4
5
6 Function: a performance measuring tool that analyzes the time spent
7 executing each source statement of a program, along with other
8 parameters of interest, after the program is run.
9
10
11 Arguments:
12 program_names
13 are pathnames or reference names of programs to be analyzed. Any
14 program_name that does not include "<" or ">" characters is assumed
15 to be a reference name. They need not be specified if the
16 -input_file control argument is used.
17
18
19 Control arguments: Control arguments apply to all programs specified,
20 and can be given in any order.
21 -brief, -bf
22 used with -print to exclude from the output all information for
23 statements that have never been executed. This is the default.
24 -comment STR, -com STR
25 used with the -output_file control argument to include STR with the
26 stored profile data as a comment. This control argument can also be
27 used with -plot. If STR is to include blanks or other characters
28 recognized as special by the command processor, it should be
29 enclosed in quotes. STR can be up to 128 characters long.
30 -first N, -ft N
31 used with -sort to print only the first N values.
32
33
34 -from N, -fm N
35 used with -print or -plot to begin the output with the data for line
36 number N. The default is 1.
37 -hardcore, -hard
38 indicates that the specified programs are supervisor hardcore
39 segments. The current internal static profile data for such
40 programs is retrieved from the address space of the supervisor.
41 Hardcore programs compiled with the -profile or -long_profile
42 control arguments must be installed by generating a Multics System
43 Tape and rebooting Multics. See System Programming Tools, Order
44 No. AZ03, for a description of the generate_mst command. Note that
45 the current internal static profile data for hardcore programs
46 cannot be reset zeroed.
47
48
49 -input_file path, -if path
50 causes the profile data to be retrieved from the profile data file
51 specified by path. Use of this control argument causes the current
52 internal static profile data, if any, to be ignored. The pfd
53 suffix is appended to path if it is not already present. If any
54 program_names are specified, they select a subset of the stored data
55 for analysis. If no program_names are specified, all data stored in
56 the profile data file is used. This control argument is
57 inconsistent with -output_file.
58 -line_length N, -ll N
59 used with -list to specify an output width of N characters. The
60 default is 132.
61
62
63 -list, -ls
64 creates a profile listing for all specified programs. The profile
65 listing file is given a name consisting of the first program name
66 with the language suffix replaced by the pfl suffix. It is placed
67 in the working directory. The information described above for the
68 -print control argument is placed in columns to the left of each
69 source line in the profile listing.
70 -long, -lg
71 used with -print to include in the output information for statements
72 that have never been executed.
73 -max_points N, -mp N
74 used with -plot to specify the maximum number of points line
75 numbers to be plotted the graphics resolution. The default is
76 250. The Multics Graphics System is capable of plotting up to 1024
77 points.
78
79
80 -no_header, -nhe
81 used with -print to suppress column headings.
82 -output_file path, -of path
83 causes the profile data for the specified program_names to be stored
84 in the profile data file specified by path. The file is created if
85 it does not already exist and is overwritten if it already exists.
86 The pfd suffix is added to path if it is not already present. The
87 profile data is stored in a format acceptable to the -input_file
88 control argument. The format of pfd data files is described by the
89 PL/I include file pfd_format.incl.pl1. The stored data is
90 determined by the program_names specified, the -comment control
91 argument and whether the compilation was done using the -profile or
92 -long_profile options. The name a program was compiled with is
93 saved in the profile data file. If program_name specifies a bound
94 object segment, profile data about each component of the bound
95 object segment is saved.
96
97
98 -plot STR
99 plots a bar graph, on any supported graphics terminal, of the values
100 of the specified field STR. STR can be any of the fields in the
101 "List of Fields" section below. Use of this control argument
102 requires that the site has installed the Multics Graphics System,
103 and that the setup_graphics command has been executed. See the
104 Multics Graphics System, Order No. AS40, for more information.
105
106
107 -print, -pr
108 prints the following information for each statement in the specified
109 programs:
110 1. Line Number.
111 2. Statement Number
112 if more than one statement on the line.
113 3. Count
114 the number of times the statement was executed.
115 4. Cost
116 an approximation to the accumulated execution time for the
117 statement. Equal to the number of instructions executed plus
118 ten times the number of external operators called.
119
120
121 5. Stars asterisks
122 an indication of the percentage of total cost or time for
123 long_profile data used in the statement. The number of stars
124 is selected according to the table below.
125
126 4 stars: 20% to 100%
127 3 stars: 10% to 20%
128 2 stars: 5% to 10%
129 1 star: 2.5% to 5%
130 no stars: 0% to 2.5%
131 one period: Statement was not executed.
132
133 6. Names of all external operators called by the statement.
134
135
136 For -long_profile actual accumulated time data, item 4 is changed
137 to the following:
138 4a. Time
139 actual execution time for the statement in virtual CPU
140 microseconds, including all time spent in any operators or
141 subroutines invoked by the statement.
142 4b. Average Time
143 Time divided by Count the average execution time for one
144 execution of the statement.
145 4c. Page Faults
146 page faults incurred in executing the statement.
147
148
149 -reset, -rs
150 resets zeros all current internal static profile data for the
151 named programs. When -reset is specified, the resetting is done
152 as the very last operation if -print, -list, -plot, or -output_file
153 are also specified. This control argument is inconsistent with
154 -input_file and -hardcore.
155 -search_dir path, -srhd path
156 used with -hardcore to add path to an internal search list of
157 hardcore object directories. Up to 8 directories can be specified.
158 If no search list is specified, >ldd>hard>o is searched for copies
159 of the specified programs.
160 -sort STR
161 used with -print to sort profile information into descending order
162 of the specified field STR, which can be any of the fields in the
163 "List of Fields" section below.
164
165
166 -source_dir path, -scd path
167 used with -list when the source segments to be listed have been
168 moved from the directories in which they were compiled. If
169 -source_dir is specified, only the directory specified by pathname
170 path is searched for source segments.
171 -to N
172 used with -print or -plot to end the output with the data for line
173 number N. The default is the line number of the last executable
174 statement.
175
176
177 List of Fields:
178 count
179 number of times statement was executed.
180 time
181 vpcu time of statement -long_profile.
182 cost
183 approximate cost of statement -profile.
184 page_faults pfs
185 page faults taken during statement -long_profile.
186
187
188
189 Notes: The program to be analyzed must be compiled using the -profile
190 -pf control argument of the cobol, fortran and pl1 commands, or using
191 the -long_profile -lpf control argument of the pl1 command. The
192 -long_profile compiler control argument is used to acquire exact
193 elapsed time statistics and is much more expensive to use than the
194 -profile compiler control argument.
195