Product SiteDocumentation Site

3.8.8.3.  pmRecordSetup Function

FILE *pmRecordSetup(const char *folio, const char *creator, int replay)
Python:
int status = pmRecordSetup("folio string", "creator string", int replay)
The pmRecordSetup function along with the pmRecordAddHost and pmRecordControl functions may be used to create a PCP archive on the fly to support record-mode services for PMAPI client applications.
Each record mode session involves one or more PCP archive logs; each is created using a dedicated pmlogger process, with an overall Archive Folio format as understood by the pmafm command, to name and collect all of the archive logs associated with a single recording session.
The pmRecordHost structure is used to maintain state information between the creator of the recording session and the associated pmlogger process(es). The structure, shown in Example 3.16, “ pmRecordHost Structure”, is defined as:

Example 3.16.  pmRecordHost Structure

typedef struct {
    FILE   *f_config;    /* caller writes pmlogger configuration here */
    int    fd_ipc;       /* IPC channel to pmlogger */
    char   *logfile;     /* full pathname for pmlogger error logfile */
    pid_t  pid;          /* process id for pmlogger */
    int    status;       /* exit status, -1 if unknown */
} pmRecordHost;
In Procedure 3.1, “Creating a Recording Session”, the functions are used in combination to create a recording session.

Procedure 3.1. Creating a Recording Session

  1. Call pmRecordSetup to establish a new recording session. A new Archive Folio is created using the name folio. If the folio file or directory already exists, or if it cannot be created, this is an error. The application that is creating the session is identified by creator (most often this would be the same as the global PMAPI application name, as returned pmGetProgname()). If the application knows how to create its own configuration file to replay the recorded session, replay should be nonzero. The pmRecordSetup function returns a stdio stream onto which the application writes the text of any required replay configuration file.
  2. For each host that is to be included in the recording session, call pmRecordAddHost. A new pmRecordHost structure is returned via rhp. It is assumed that PMCD is running on the host as this is how pmlogger retrieves the required performance metrics. See Section 3.8.8.1, “ pmRecordAddHost Function” for more information.
  3. Optionally, add arguments to the command line that is used to launch pmlogger by calling pmRecordControl with a request of PM_REC_SETARG. The argument is passed via options and one call to pmRecordControl is required for each distinct argument. See Section 3.8.8.2, “ pmRecordControl Function” for more information.
  4. To commence the recording session, call pmRecordControl with a request of PM_REC_ON, and rhp must be NULL.
  5. To terminate a pmlogger instance identified by rhp, call pmRecordControl with a request of PM_REC_OFF.
  6. To display the current status of the pmlogger instance identified by rhp, call pmRecordControl with a request of PM_REC_STATUS.
  7. To detach a pmlogger instance identified by rhp, allow it to continue independent of the application that launched the recording session, call pmRecordControl with a request of PM_REC_DETACH.
The calling application should not close any of the returned stdio streams; pmRecordControl performs this task when recording is commenced.
Once pmlogger has been started for a recording session, pmlogger assumes responsibility for any dialogue with the user in the event that the application that launched the recording session should exit, particularly without terminating the recording session.
By default, information and dialogues from pmlogger is displayed using pmconfirm. This default is based on the assumption that most applications launching a recording session are GUI-based. In the event that pmconfirm fails to display the information (for example, because the DISPLAY environment variable is not set), pmlogger writes on its own stderr stream (not the stderr stream of the launching process). The output is assigned to the xxxxxx.host.log file. For convenience, the full pathname to this file is provided via the logfile field in the pmRecordHost structure.
If the options argument to pmRecordControl is not NULL, this string may be used to pass additional arguments to pmconfirm in those cases where a dialogue is to be displayed. One use of this capability is to provide a -geometry string to control the placement of the dialogue.
Premature termination of a launched pmlogger process may be determined using the pmRecordHost structure, by calling select on the fd_ipc field or polling the status field that will contain the termination status from waitpid if known, or -1.
These functions create a number of files in the same directory as the folio file named in the call to pmRecordSetup. In all cases, the xxxxxx component is the result of calling mkstemp.
  • If replay is nonzero, xxxxxx is the creator's replay configuration file, else an empty control file, used to guarantee uniqueness.
  • The folio file is the PCP Archive Folio, suitable for use with the pmafm command.
  • The xxxxxx.host.config file is the pmlogger configuration for each host. If the same host is used in different calls to pmRecordAddHost within the same recording session, one of the letters 'a' through 'z' is appended to the xxxxxx part of all associated file names to ensure uniqueness.
  • xxxxxx.host.log is stdout and stderr for the pmlogger instance for each host.
  • The xxxxxx.host.{0,meta,index} files comprise a single PCP archive for each host.
pmRecordSetup may return NULL in the event of an error. Check errno for the real cause. The value EINVAL typically means that the order of calls to these functions is not correct; that is, there is an obvious state associated with the current recording session that is maintained across calls to the functions.
For example, calling pmRecordControl before calling pmRecordAddHost at least once, or calling pmRecordAddHost before calling pmRecordSetup would produce an EINVAL error.