This section describes the tasks you can accomplish with the API:
• Change Output Directory
• Get Version Information
• Manipulate Profiles
10.4.1 Change Output Directory
The default output directory for both the log files and the resulting HTML report file is the manager's directory of the Caché instance (install-dir\mgr) for which you are running the ^pButtons utility. You can change the default directory using the commands described in the following table.
Note: These commands do not affect currently running profiles, whether or not the HTML report files have been produced;
that is, no files associated with currently running profiles are moved to the new output directory.
Description Command
Sets the pathname of output directory to directory; if the does not exist, it is created.
Note: If you do not specify an absolute pathname (for example, C:\pButtonReports), the directory is assumed to be relative to the manager's directory.
do setlogdir^pButtons("directory")
Resets the output directory pathname to the default manager's directory.
do clrlogdir^pButtons()
10.4.2 Get Version Information
You can find the current version of the ^pButtons utility using the following commands:
• write $$version^pButtons()
• set ver=$$version^pButtons()
10.4.3 Manipulate Profiles
You can use the APIs described in the following sections to manipulate the profile definitions.
• Create New Profiles
• Edit Profiles
• Copy Profiles
• Delete Profiles
10.4.3.1 Create New Profiles
You can create a new profile with the following API command:
set rc=$$addprofile^pButtons("profilename","description",interval,count)
where profilename, which is required, must be unique and cannot contain spaces or white-noise characters; description, which is required, should be meaningful because it displayed in the menu when you run the ^pButtons utility; interval, which is required, is the frequency with which to run each sample, in seconds (in the range of 1 second to 300 seconds);
and count, which is required, is the number of times to run the profile.
For example, to create a profile named 2minrun that runs a sampling every 10 seconds until it runs 12 samplings (for a total of 120 seconds, or two minutes), enter the following:
set rc=$$addprofile^pButtons("2minrun","A 2-minute run sampling every 10 seconds",10,12)
The next time you run the ^pButtons utility, the list of profiles includes the following profile name and description:
2minrun A 2-minute run sampling every 10 seconds
Generate Profile
Alternatively, you can quickly generate new profiles (with a meaningful name and description) with the following API command:
set rc=$$genprofile^pButtons("duration"[,interval])
where duration (interval * count), which is required, must be in the format "hh:mm", "hh:", or mm; and interval, which is optional, is the frequency with which to run each sample.
Note: The maximum duration is 24 hours (86400 seconds); if you specify a longer duration, ^pButtons reduces it to 24 hours. The duration must be double-quoted only if it contains a colon (:); the colon denotes hours.
The minimum interval, if specified, is 2 seconds, unless the duration (that is, interval * count) is less than one hour, in which case the minimum interval is 1 second). If you specify an invalid interval, ^pButtons increases it to the required minimum. If the interval is not specified, it defaults to 10 seconds.
For example, to generate a profile named 12hours (with a generated profile name and description) that runs samples every 5 minutes (300 seconds) over 12 hours, enter the following:
set rc=$$genprofile^pButtons("12:",300)
In addition, to generate a profile named 90mins that runs samples every 10 seconds for 90 minutes, enter the following:
set rc=$$genprofile^pButtons(90)
The next time you run the ^pButtons utility, the list of profiles includes the following profile names and descriptions:
12hours A 12 hour run sampling every 300 seconds 90mins A 90 minute run sampling every 10 seconds
10.4.3.2 Edit Profiles
You can edit an existing profile (except for the predefined “test” profile) with the following API command:
set rc=$$editprofile^pButtons("profilename","description",[interval],[count])
where profilename, which is required, must be unique and cannot contain spaces or white-noise characters; description, which is required, should be meaningful because it displayed in the menu when you run the ^pButtons utility; interval, which is optional, is the time to run each sample, in seconds (in the range of 2 seconds to 300 seconds); and count, which is optional, is the number of times to run the profile.
Note: The arguments are positional; if, for example, to edit the count argument (and keep the value specified in the interval argument), you must include the comma separator, as follows: set
rc=$$editprofile^pButtons("2minrun","A 5-minute run sampling every 30 seconds",,50).
If the duration exceeds 24 hours (86400 seconds), it is automatically reduced to 24 hours.
For example, to modify the 2minrun profile to run a sampling every 30 seconds until it runs 10 samplings (for a total of 300 seconds, or five minutes), enter the following:
set rc=$$editprofile^pButtons("2minrun","A 5-minute run sampling every 30 seconds",30,10)
The next time you run the ^pButtons utility, the list of profiles includes the following profile name and description:
2minrun A 5-minute run sampling every 30 seconds
10.4.3.3 Copy Profiles
You can copy an existing profile to a file with a different name with the following API command:
set rc=$$copyprofile^pButtons("sourceprofilename","targetprofilename")
where sourceprofilename, which is required, is the name of an existing profile, and targetprofilename, which is required, must be unique and cannot contain spaces or white-noise characters.
For example, to make a copy of the 2minrun profile, enter the following:
set rc=$$copyprofile^pButtons("2minrun","5minrun")
The next time you run the ^pButtons utility, the list of profiles includes the following profile names and description:s
2minrun A 2-minute run sampling every 30 seconds 5minrun A 2-minute run sampling every 30 seconds
You can now edit the new profile as described in Edit Profiles in this section of the guide.
10.4.3.4 Delete Profiles
You can delete existing profiles (except for the predefined “test” profile) with the following API command:
set rc=$$delprofile^pButtons("profilename")
where profilename, which is required and must be double-quoted, is the name of the profile you want to delete.
For example, to delete the 2minrun profile, enter the following:
set rc=$$delprofile^pButtons("2minrun")
The next time you run the ^pButtons utility, the list of profiles does not include 2minrun profile.