PMTIME(3)						     Library Functions Manual							 PMTIME(3)

NAME

       pmtime, pmTimeConnect, pmTimeDisconnect, pmTimeRecv, pmTimeSendAck, pmTimeShowDialog - time control functions for synchronizing the archive
       position and update interval between one or more applications

C SYNOPSIS

       #include <pcp/pmtime.h>

       int pmTimeConnect(int port, pmTime *state);
       int pmTimeDisconnect(int fd);
       int pmTimeSendAck(int fd, struct timeval *fetchTime);
       int pmTimeShowDialog(int fd, int show);
       int pmTimeRecv(int fd, pmTime *state);

       cc ... -lpcp_gui

DESCRIPTION

       These functions form part of the Performance Metrics Applications Programming Interface (PMAPI) and are intended to provide a uniform mech-
       anism for applications to both replay archive data and report live data in a time synchronized manner.

       The pmTime structure has the following fields:
	 typedef struct {
	     unsigned int	 magic;
	     unsigned int	 length;
	     pm_tctl_command	 command;
	     pm_tctl_source	 source;
	     pm_tctl_state	 state;
	     pm_tctl_mode	 mode;
	     struct timeval	 delta;
	     struct timeval	 position;
	     struct timeval	 start;     /* archive only */
	     struct timeval	 end;	    /* archive only */
	     char		 data[0];   /* arbitrary length info (TZ) */
	 } pmTime;

       In  the simplest case, the application should call pmTimeConnect to connect to the time control server, pmtime(1), and then repeatedly call
       pmTimeRecv in the main loop of the application.	On success, pmTimeConnect returns a non-negative file descriptor.  In  applications  which
       have  multiple  threads	of  control, rather than simply blocking in pmTimeRecv, the file descriptor may be used in calls to select(2).	In
       graphical applications, the file descriptor may be used to interface with the event loop.

       The port parameter to pmTimeConnect is the port number of the socket on which the time control server is (or will  be)  listening  for  new
       connections.

       The  state parameter to pmTimeConnect is used to initialize a new time control server or to pass additional information to an existing time
       control server.	The start and finish fields indicate the chronological bounds interesting to the application.  The showdialog field  indi-
       cates  whether the time control server should initially show or hide the dialog.  The position, delta, and data fields indicate the initial
       archive position, update interval, time zone string and time zone label string.

       pmTimeRecv blocks until the time control server sends a command message.  It then updates the  state  parameter	and  returns  one  of  the
       PM_TCTL command identifiers.

       The  PM_TCTL_SET command indicates the application should seek to the archive position (see pmSetMode(3)) returned in the position field of
       the state parameter.

       The PM_TCTL_STEP command indicates the application should perform an update, i.e. advance (or rewind, if delta is  negative)  to  the  time
       indicated  by  position	and then fetch new metric values, update the display or whatever.  In order for several application to remain syn-
       chronized, the time control server will wait until all applications have acknowledged that they have completed the step command.   Applica-
       tions  should  call  pmTimeSendAck  when  the step command has been processed.  Note that PM_TCTL_STEP is the only command that requires an
       explicit acknowledgement.

       The PM_TCTL_VCRMODE command is used by the time control server to indicate the current VCR mode.

       The value is returned in the vcrmode field of the state parameter passed to pmTimeRecv, and remains valid until	the  next  PM_TCTL_VCRMODE
       command is received.

       The PM_TCTL_TZ command indicates the application should use a new time- zone, as indicated in the tz and tzlabel fields of the state param-
       eter.

       The PM_TCTL_BOUNDS command is sent to all applications when the time control server changes its chronological bounds.  This may occur  when
       a new application connects to the time control server or the user changes the bounds manually.  Most applications will ignore this command.

       The PM_TCTL_SHOWDIALOG command will be sent to all applications when the visibility of the time control server changes.	This allows appli-
       cations to alter the text in menus or buttons to reflect this change.  Applications may change the visibility of the  time  control  dialog
       using  the pmTimeShowDialog function.  The initial visibility is determined when the time control dialog is first created by an application
       calling pmTimeConnect with the showdialog field in the state parameter set to the desired value.

       The pmTimeDisconnect function may be used to close the command socket to the time control server.  This is useful when applications need to
       change the connection mode, e.g. to divorce the current time control server and connect to a new one.

SEE ALSO

       pmtime(1), PMAPI(3) and pmSetMode(3).

Performance Co-Pilot						      Aconex								 PMTIME(3)