12/22/80 profile, pf Syntax: pf {program_names} {-control_args} Function: a performance measuring tool that analyzes the time spent executing each source statement of a program, along with other parameters of interest, after the program is run. Arguments: program_names are pathnames or reference names of programs to be analyzed. Any program_name that does not include "<" or ">" characters is assumed to be a reference name. They need not be specified if the -input_file control argument is used. Control arguments: Control arguments apply to all programs specified, and can be given in any order. -brief, -bf used with -print to exclude from the output all information for statements that have never been executed. This is the default. -comment STR, -com STR used with the -output_file control argument to include STR with the stored profile data as a comment. This control argument can also be used with -plot. If STR is to include blanks or other characters recognized as special by the command processor, it should be enclosed in quotes. STR can be up to 128 characters long. -first N, -ft N used with -sort to print only the first N values. -from N, -fm N used with -print or -plot to begin the output with the data for line number N. The default is 1. -hardcore, -hard indicates that the specified programs are supervisor (hardcore) segments. The current (internal static) profile data for such programs is retrieved from the address space of the supervisor. Hardcore programs compiled with the -profile or -long_profile control arguments must be installed by generating a Multics System Tape and rebooting Multics. See System Programming Tools, Order No. AZ03, for a description of the generate_mst command. Note that the current (internal static) profile data for hardcore programs cannot be reset (zeroed). -input_file path, -if path causes the profile data to be retrieved from the profile data file specified by path. Use of this control argument causes the current (internal static) profile data, if any, to be ignored. The pfd suffix is appended to path if it is not already present. If any program_names are specified, they select a subset of the stored data for analysis. If no program_names are specified, all data stored in the profile data file is used. This control argument is inconsistent with -output_file. -line_length N, -ll N used with -list to specify an output width of N characters. The default is 132. -list, -ls creates a profile listing for all specified programs. The profile listing file is given a name consisting of the first program name with the language suffix replaced by the pfl suffix. It is placed in the working directory. The information described above for the -print control argument is placed in columns to the left of each source line in the profile listing. -long, -lg used with -print to include in the output information for statements that have never been executed. -max_points N, -mp N used with -plot to specify the maximum number of points (line numbers) to be plotted (the graphics resolution). The default is 250. The Multics Graphics System is capable of plotting up to 1024 points. -no_header, -nhe used with -print to suppress column headings. -output_file path, -of path causes the profile data for the specified program_names to be stored in the profile data file specified by path. The file is created if it does not already exist and is overwritten if it already exists. The pfd suffix is added to path if it is not already present. The profile data is stored in a format acceptable to the -input_file control argument. The format of pfd data files is described by the PL/I include file pfd_format.incl.pl1. The stored data is determined by the program_names specified, the -comment control argument and whether the compilation was done using the -profile or -long_profile options. The name a program was compiled with is saved in the profile data file. If program_name specifies a bound object segment, profile data about each component of the bound object segment is saved. -plot STR plots a bar graph, on any supported graphics terminal, of the values of the specified field STR. STR can be any of the fields in the "List of Fields" section below. Use of this control argument requires that the site has installed the Multics Graphics System, and that the setup_graphics command has been executed. See the Multics Graphics System, Order No. AS40, for more information. -print, -pr prints the following information for each statement in the specified program(s): 1. Line Number. 2. Statement Number if more than one statement on the line. 3. Count the number of times the statement was executed. 4. Cost an approximation to the accumulated execution time for the statement. Equal to the number of instructions executed plus ten times the number of external operators called. 5. Stars (asterisks) an indication of the percentage of total cost (or time, for long_profile data) used in the statement. The number of stars is selected according to the table below. 4 stars: 20% to 100% 3 stars: 10% to 20% 2 stars: 5% to 10% 1 star: 2.5% to 5% no stars: 0% to 2.5% one period: Statement was not executed. 6. Names of all external operators called by the statement. For -long_profile (actual accumulated time) data, item 4 is changed to the following: 4a. Time actual execution time for the statement in virtual CPU microseconds, including all time spent in any operators or subroutines invoked by the statement. 4b. Average Time Time divided by Count (the average execution time for one execution of the statement). 4c. Page Faults page faults incurred in executing the statement. -reset, -rs resets (zeros) all current (internal static) profile data for the named program(s). When -reset is specified, the resetting is done as the very last operation if -print, -list, -plot, or -output_file are also specified. This control argument is inconsistent with -input_file and -hardcore. -search_dir path, -srhd path used with -hardcore to add path to an internal search list of hardcore object directories. Up to 8 directories can be specified. If no search list is specified, >ldd>hard>o is searched for copies of the specified program(s). -sort STR used with -print to sort profile information into descending order of the specified field STR, which can be any of the fields in the "List of Fields" section below. -source_dir path, -scd path used with -list when the source segments to be listed have been moved from the directories in which they were compiled. If -source_dir is specified, only the directory specified by pathname path is searched for source segments. -to N used with -print or -plot to end the output with the data for line number N. The default is the line number of the last executable statement. List of Fields: count number of times statement was executed. time vpcu time of statement (-long_profile). cost approximate cost of statement (-profile). page_faults (pfs) page faults taken during statement (-long_profile). Notes: The program to be analyzed must be compiled using the -profile (-pf) control argument of the cobol, fortran and pl1 commands, or using the -long_profile (-lpf) control argument of the pl1 command. The -long_profile compiler control argument is used to acquire exact elapsed time statistics and is much more expensive to use than the -profile compiler control argument. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved