This chapter contains the syntax man pages for the tracing routines used in the Visualization Tool Tracing Subsystem Tracing Subsystem. These user-callable routines allow the programmer to customize the trace collection from within the application being traced. Included are functions for:
There is a C version and a Fortran version for each of the routines.
The tracing routines are:
For more information, see IBM Parallel Environment for AIX: Operation and Use, Volume 2.
Purpose
Flushes the memory buffer to the trace collection directory.
Version
The above are automatically included by the POE functions.
C Synopsis
#include <VT_trc.h> int VT_trc_flush_c();
Fortran Synopsis
VT_TRC_FLUSH(INTEGER RETURN_CODE)
Parameters
In Fortran, the following applies:
Description
This routine may be called from the application to flush the memory buffer to the trace collection directory. This is specified by the MP_TRACE directory environment variable or -tracedir parameter and defaults to the directory from which the application was stored.
Return Values
In C and C++ calls, the following applies:
Errors
The application could not contact the kernel statistics sampling daemon.
For more information about error conditions, refer to IBM Parallel Environment for AIX: Messages .
Examples
C Example
#include <stdlib.h>
#include <stdio.h>
#include <mpi.h>
#include <VT_trc.h>
#define COUNT 1024
int main(int argc, char **argv)
{
int i;
int numtask;
int taskid;
int msg_in[COUNT], msg_out[COUNT];
int src, dest, len, send_msgid, recv_msgid, nBytes;
/* Find out number of tasks/nodes. */
MPI_Init( &argc, &argv);
MPI_Comm_size( MPI_COMM_WORLD, &numtask);
MPI_Comm_rank( MPI_COMM_WORLD, &taskid);
/****************************************************
Set tracing parameters as follows:
Memory buffer = 500K
Temporary trace file = 1M
Sample every second
Do not use wrap around buffer
****************************************************/
if(0!=VT_trc_set_params_c(500000,1000000,1000,0))
{
printf("Could not reset trace parameters!\n");
}
/* Disable tracing while the message buffer is being initialized */
if(0!=VT_trc_stop_c())
{
printf("Could not stop tracing!\n");
}
/* Flush the memory buffer to disk */
if(0!=VT_trc_flush_c())
{
printf("Could not flush trace buffer!\n");
}
for(i=0;i<COUNT;i++)
msg_out[i]=taskid;
/* Re-enable tracing. Level 9 asks for everything */
/* but only events enabled by the command line or */
/* environment variable will be re-enabled) */
if(0!=VT_trc_start_c(9))
{
printf("Could not restart tracing!\n");
}
dest = (taskid<(numtask-1))?(taskid+1):0;
MPI_Send(msg_out, COUNT, MPI_INT, dest, 0, MPI_COMM_WORLD);
src = (taskid>0)?(taskid-1):(numtask-1);
MPI_Recv(msg_in, COUNT, MPI_INT, src, 0, MPI_COMM_WORLD);
MPI_Finalize();
}
Fortran Example
PROGRAM TRCDEMO
C
INCLUDE "mpif.h"
IMPLICIT NONE
INTEGER COUNT, I
INTEGER BUFFSZ, FILESZ
INTEGER SMPL, WRAP
PARAMETER ( COUNT = 1024 )
PARAMETER ( BUFFSZ = 500000, FILESZ = 1000000 )
PARAMETER ( SMPL = 1000, WRAP = 0 )
INTEGER MSG_IN(COUNT), MSG_OUT(COUNT)
INTEGER NUMTASK, TASKID
INTEGER SRC, DEST
INTEGER RC
C
C FIND OUT NUMBER OF TASKS
CALL MPI_INIT( RC )
CALL MPI_COMM_SIZE( MPI_COMM_WORLD, NUMTASK, RC )
CALL MPI_COMM_RANK( MPI_COMM_WORLD, TASKID, RC )
C
C
C SET TRACING PARAMETERS AS FOLLOWS:
C MEMORY BUFFER = 500K
C TEMPORARY TRACE FILE = 1M
C SAMPLE EVERY SECOND
C DO NOT USE WRAP AROUND BUFFER
C
C
CALL VT_TRC_SET_PARAMS(BUFFSZ, FILESZ, SMPL, WRAP, RC)
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not reset trace parameters!'
ENDIF
C DISABLE TRACING WHILE THE MESSAGE BUFFER IS BEING INITIALIZED
CALL VT_TRC_STOP( RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not stop tracing!'
ENDIF
C FLUSH THE MEMORY BUFFER TO DISK
CALL VT_TRC_FLUSH( RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not flush trace buffer!'
ENDIF
DO I = 1,COUNT
MSG_OUT(I) = TASKID
ENDDO
C RE-ENABLE TRACING. LEVEL 9 ASKS FOR EVERYTHING
C BUT ONLY EVENTS ENABLED BY THE COMMAND LINE OR
C ENVIRONMENT VARIABLE WILL BE RE-ENABLED)
CALL VT_TRC_START( 9, RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not restart tracing!'
ENDIF
IF( TASKID .GE. NUMTASK-1 ) THEN
DEST = 0
ELSE
DEST = TASKID + 1
ENDIF
CALL MPI_SEND(MSG_OUT, COUNT, MPI_INTEGER, DEST, 0,
+ MPI_COMM_WORLD, RC )
IF( TASKID .LE. 0 ) THEN
SRC = NUMTASK - 1
ELSE
SRC = TASKID - 1
ENDIF
CALL MPI_RECV(MSG_IN, COUNT, MPI_INTEGER, SRC, 0,
+ MPI_COMM_WORLD, RC)
CALL MPI_FINALIZE( RC )
STOP
END
C
Related Information
Functions:
For more information about VT tracing, see IBM Parallel Environment for AIX: Operation and Use, Volume 2.
Purpose
Lets applications set tracing parameters.
Version
The above are automatically included by the POE.
C Synopsis
#include <VT_trc.h>
int VT_trc_set_params_c(size_t buff_size, size_t file_size,
int sampling_freq, int wrap_around_flag);
Fortran Synopsis
VT_TRC_SET_PARAMS(INTEGER BUFF_SIZE, INTEGER FILE_SIZE,
INTEGER SAMPLING_FREQ, INTEGER WRAP_AROUND_FLAG,
INTEGER RETURN_CODE)
Parameters
Description
This routine allows applications to set certain tracing parameters, such as:
Notes
Return Values
In C and C++ calls, the following applies:
Errors
You tried to set the size of the temporary file less than the minimum threshold size. The program automatically set the size to the minimum and continued trace generation.
Change the parameters in VT_TRC_SET_PARAMS call above the threshold value.
You tried to set the size of the trace buffer less than the minimum threshold size. The program automatically set the size to the threshold size and continued trace generation.
Change the parameters in VT_TRC_SET_PARAMS call above the threshold value.
You tried to set the sampling frequency to be less than the minimum threshold value. The program automatically set the size to the threshold value and continued trace generation.
Change the parameters in VT_TRC_SET_PARAMS call above the threshold value.
The application could not obtain the memory required to change parameters.
The application could not contact the kernel statistics sampling daemon.
For more information about error conditions, refer to IBM Parallel Environment for AIX: Messages .
Examples
C Example
#include <stdlib.h>
#include <stdio.h>
#include <mpi.h>
#include <VT_trc.h>
#define COUNT 1024
int main(int argc, char **argv)
{
int i;
int numtask;
int taskid;
int msg_in[COUNT], msg_out[COUNT];
int src, dest, len, send_msgid, recv_msgid, nBytes;
/* Find out number of tasks/nodes. */
MPI_Init( &argc, &argv);
MPI_Comm_size( MPI_COMM_WORLD, &numtask);
MPI_Comm_rank( MPI_COMM_WORLD, &taskid);
/****************************************************
Set tracing parameters as follows:
Memory buffer = 500K
Temporary trace file = 1M
Sample every second
Do not use wrap around buffer
****************************************************/
if(0!=VT_trc_set_params_c(500000,1000000,1000,0))
{
printf("Could not reset trace parameters!\n");
}
/* Disable tracing while the message buffer is being initialized */
if(0!=VT_trc_stop_c())
{
printf("Could not stop tracing!\n");
}
/* Flush the memory buffer to disk */
if(0!=VT_trc_flush_c())
{
printf("Could not flush trace buffer!\n");
}
for(i=0;i<COUNT;i++)
msg_out[i]=taskid;
/* Re-enable tracing. Level 9 asks for everything */
/* but only events enabled by the command line or */
/* environment variable will be re-enabled) */
if(0!=VT_trc_start_c(9))
{
printf("Could not restart tracing!\n");
}
dest = (taskid<(numtask-1))?(taskid+1):0;
MPI_Send(msg_out, COUNT, MPI_INT, dest, 0, MPI_COMM_WORLD);
src = (taskid>0)?(taskid-1):(numtask-1);
MPI_Recv(msg_in, COUNT, MPI_INT, src, 0, MPI_COMM_WORLD);
MPI_Finalize();
}
Fortran Example
PROGRAM TRCDEMO
C
INCLUDE "mpif.h"
IMPLICIT NONE
INTEGER COUNT, I
INTEGER BUFFSZ, FILESZ
INTEGER SMPL, WRAP
PARAMETER ( COUNT = 1024 )
PARAMETER ( BUFFSZ = 500000, FILESZ = 1000000 )
PARAMETER ( SMPL = 1000, WRAP = 0 )
INTEGER MSG_IN(COUNT), MSG_OUT(COUNT)
INTEGER NUMTASK, TASKID
INTEGER SRC, DEST
INTEGER RC
C
C FIND OUT NUMBER OF TASKS
CALL MPI_INIT( RC )
CALL MPI_COMM_SIZE( MPI_COMM_WORLD, NUMTASK, RC )
CALL MPI_COMM_RANK( MPI_COMM_WORLD, TASKID, RC )
C
C
C SET TRACING PARAMETERS AS FOLLOWS:
C MEMORY BUFFER = 500K
C TEMPORARY TRACE FILE = 1M
C SAMPLE EVERY SECOND
C DO NOT USE WRAP AROUND BUFFER
C
C
CALL VT_TRC_SET_PARAMS(BUFFSZ, FILESZ, SMPL, WRAP, RC)
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not reset trace parameters!'
ENDIF
C DISABLE TRACING WHILE THE MESSAGE BUFFER IS BEING INITIALIZED
CALL VT_TRC_STOP( RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not stop tracing!'
ENDIF
C FLUSH THE MEMORY BUFFER TO DISK
CALL VT_TRC_FLUSH( RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not flush trace buffer!'
ENDIF
DO I = 1,COUNT
MSG_OUT(I) = TASKID
ENDDO
C RE-ENABLE TRACING. LEVEL 9 ASKS FOR EVERYTHING
C BUT ONLY EVENTS ENABLED BY THE COMMAND LINE OR
C ENVIRONMENT VARIABLE WILL BE RE-ENABLED)
CALL VT_TRC_START( 9, RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not restart tracing!'
ENDIF
IF( TASKID .GE. NUMTASK-1 ) THEN
DEST = 0
ELSE
DEST = TASKID + 1
ENDIF
CALL MPI_SEND(MSG_OUT, COUNT, MPI_INTEGER, DEST, 0,
+ MPI_COMM_WORLD, RC )
IF( TASKID .LE. 0 ) THEN
SRC = NUMTASK - 1
ELSE
SRC = TASKID - 1
ENDIF
CALL MPI_RECV(MSG_IN, COUNT, MPI_INTEGER, SRC, 0,
+ MPI_COMM_WORLD, RC)
CALL MPI_FINALIZE( RC )
STOP
END
C
Related Information
Functions:
For more information about VT tracing, see IBM Parallel Environment for AIX: Operation and Use, Volume 2.
Purpose
Lets an application start a trace from within the program.
Version
The above is automatically included by the POE functions.
C Synopsis
#include <VT_trc.h> int VT_trc_start_c(int flag);
Fortran Synopsis
VT_TRC_START(INTEGER FLAG, INTEGER RETURN_CODE)
Parameters
Description
This routine can be called by the application program. This lets the program start the trace from within the program, dynamically and selectively. The flag has the same meaning as the trace flag passed by PM upon startup. If the flag indicates VT_AIX_TRACE, this routine also sends a message to the monitoring daemon task.
Notes
Return Values
In C and C++ calls, the following applies:
Errors
The application could not contact the kernel statistics sampling daemon.
For more information about error conditions, see IBM Parallel Environment for AIX: Messages.
Examples
C Example
#include <stdlib.h>
#include <stdio.h>
#include <mpi.h>
#include <VT_trc.h>
#define COUNT 1024
int main(int argc, char **argv)
{
int i;
int numtask;
int taskid;
int msg_in[COUNT], msg_out[COUNT];
int src, dest, len, send_msgid, recv_msgid, nBytes;
/* Find out number of tasks/nodes. */
MPI_Init( &argc, &argv);
MPI_Comm_size( MPI_COMM_WORLD, &numtask);
MPI_Comm_rank( MPI_COMM_WORLD, &taskid);
/****************************************************
Set tracing parameters as follows:
Memory buffer = 500K
Temporary trace file = 1M
Sample every second
Do not use wrap around buffer
****************************************************/
if(0!=VT_trc_set_params_c(500000,1000000,1000,0))
{
printf("Could not reset trace parameters!\n");
}
/* Disable tracing while the message buffer is being initialized */
if(0!=VT_trc_stop_c())
{
printf("Could not stop tracing!\n");
}
/* Flush the memory buffer to disk */
if(0!=VT_trc_flush_c())
{
printf("Could not flush trace buffer!\n");
}
for(i=0;i<COUNT;i++)
msg_out[i]=taskid;
/* Re-enable tracing. Level 9 asks for everything */
/* but only events enabled by the command line or */
/* environment variable will be re-enabled) */
if(0!=VT_trc_start_c(9))
{
printf("Could not restart tracing!\n");
}
dest = (taskid<(numtask-1))?(taskid+1):0;
MPI_Send(msg_out, COUNT, MPI_INT, dest, 0, MPI_COMM_WORLD);
src = (taskid>0)?(taskid-1):(numtask-1);
MPI_Recv(msg_in, COUNT, MPI_INT, src, 0, MPI_COMM_WORLD);
MPI_Finalize();
}
Fortran Example
PROGRAM TRCDEMO
C
INCLUDE "mpif.h"
IMPLICIT NONE
INTEGER COUNT, I
INTEGER BUFFSZ, FILESZ
INTEGER SMPL, WRAP
PARAMETER ( COUNT = 1024 )
PARAMETER ( BUFFSZ = 500000, FILESZ = 1000000 )
PARAMETER ( SMPL = 1000, WRAP = 0 )
INTEGER MSG_IN(COUNT), MSG_OUT(COUNT)
INTEGER NUMTASK, TASKID
INTEGER SRC, DEST
INTEGER RC
C
C FIND OUT NUMBER OF TASKS
CALL MPI_INIT( RC )
CALL MPI_COMM_SIZE( MPI_COMM_WORLD, NUMTASK, RC )
CALL MPI_COMM_RANK( MPI_COMM_WORLD, TASKID, RC )
C
C
C SET TRACING PARAMETERS AS FOLLOWS:
C MEMORY BUFFER = 500K
C TEMPORARY TRACE FILE = 1M
C SAMPLE EVERY SECOND
C DO NOT USE WRAP AROUND BUFFER
C
C
CALL VT_TRC_SET_PARAMS(BUFFSZ, FILESZ, SMPL, WRAP, RC)
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not reset trace parameters!'
ENDIF
C DISABLE TRACING WHILE THE MESSAGE BUFFER IS BEING INITIALIZED
CALL VT_TRC_STOP( RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not stop tracing!'
ENDIF
C FLUSH THE MEMORY BUFFER TO DISK
CALL VT_TRC_FLUSH( RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not flush trace buffer!'
ENDIF
DO I = 1,COUNT
MSG_OUT(I) = TASKID
ENDDO
C RE-ENABLE TRACING. LEVEL 9 ASKS FOR EVERYTHING
C BUT ONLY EVENTS ENABLED BY THE COMMAND LINE OR
C ENVIRONMENT VARIABLE WILL BE RE-ENABLED)
CALL VT_TRC_START( 9, RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not restart tracing!'
ENDIF
IF( TASKID .GE. NUMTASK-1 ) THEN
DEST = 0
ELSE
DEST = TASKID + 1
ENDIF
CALL MPI_SEND(MSG_OUT, COUNT, MPI_INTEGER, DEST, 0,
+ MPI_COMM_WORLD, RC )
IF( TASKID .LE. 0 ) THEN
SRC = NUMTASK - 1
ELSE
SRC = TASKID - 1
ENDIF
CALL MPI_RECV(MSG_IN, COUNT, MPI_INTEGER, SRC, 0,
+ MPI_COMM_WORLD, RC)
CALL MPI_FINALIZE( RC )
STOP
END
C
Related Information
Functions:
For more information about VT tracing, see IBM Parallel Environment for AIX: Operation and Use, Volume 2.
Purpose
Stops collecting trace events.
Version
The above is automatically included by the POE functions.
C Synopsis
#include <VT_trc.h> int VT_trc_stop_c();
Fortran Synopsis
VT_TRC_STOP(INTEGER RETURN_CODE)
Parameters
Description
This routine can be called by the application program to stop tracing.
Return Values
In C and C++ calls, the following applies:
Errors
The application could not contact the kernel statistics sampling daemon.
For more information about error conditions, see IBM Parallel Environment for AIX: Messages .
Examples
C Example
#include <stdlib.h>
#include <stdio.h>
#include <mpi.h>
#include <VT_trc.h>
#define COUNT 1024
int main(int argc, char **argv)
{
int i;
int numtask;
int taskid;
int msg_in[COUNT], msg_out[COUNT];
int src, dest, len, send_msgid, recv_msgid, nBytes;
/* Find out number of tasks/nodes. */
MPI_Init( &argc, &argv);
MPI_Comm_size( MPI_COMM_WORLD, &numtask);
MPI_Comm_rank( MPI_COMM_WORLD, &taskid);
/****************************************************
Set tracing parameters as follows:
Memory buffer = 500K
Temporary trace file = 1M
Sample every second
Do not use wrap around buffer
****************************************************/
if(0!=VT_trc_set_params_c(500000,1000000,1000,0))
{
printf("Could not reset trace parameters!\n");
}
/* Disable tracing while the message buffer is being initialized */
if(0!=VT_trc_stop_c())
{
printf("Could not stop tracing!\n");
}
/* Flush the memory buffer to disk */
if(0!=VT_trc_flush_c())
{
printf("Could not flush trace buffer!\n");
}
for(i=0;i<COUNT;i++)
msg_out[i]=taskid;
/* Re-enable tracing. Level 9 asks for everything */
/* but only events enabled by the command line or */
/* environment variable will be re-enabled) */
if(0!=VT_trc_start_c(9))
{
printf("Could not restart tracing!\n");
}
dest = (taskid<(numtask-1))?(taskid+1):0;
MPI_Send(msg_out, COUNT, MPI_INT, dest, 0, MPI_COMM_WORLD);
src = (taskid>0)?(taskid-1):(numtask-1);
MPI_Recv(msg_in, COUNT, MPI_INT, src, 0, MPI_COMM_WORLD);
MPI_Finalize();
}
Fortran Example
PROGRAM TRCDEMO
C
INCLUDE "mpif.h"
IMPLICIT NONE
INTEGER COUNT, I
INTEGER BUFFSZ, FILESZ
INTEGER SMPL, WRAP
PARAMETER ( COUNT = 1024 )
PARAMETER ( BUFFSZ = 500000, FILESZ = 1000000 )
PARAMETER ( SMPL = 1000, WRAP = 0 )
INTEGER MSG_IN(COUNT), MSG_OUT(COUNT)
INTEGER NUMTASK, TASKID
INTEGER SRC, DEST
INTEGER RC
C
C FIND OUT NUMBER OF TASKS
CALL MPI_INIT( RC )
CALL MPI_COMM_SIZE( MPI_COMM_WORLD, NUMTASK, RC )
CALL MPI_COMM_RANK( MPI_COMM_WORLD, TASKID, RC )
C
C
C SET TRACING PARAMETERS AS FOLLOWS:
C MEMORY BUFFER = 500K
C TEMPORARY TRACE FILE = 1M
C SAMPLE EVERY SECOND
C DO NOT USE WRAP AROUND BUFFER
C
C
CALL VT_TRC_SET_PARAMS(BUFFSZ, FILESZ, SMPL, WRAP, RC)
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not reset trace parameters!'
ENDIF
C DISABLE TRACING WHILE THE MESSAGE BUFFER IS BEING INITIALIZED
CALL VT_TRC_STOP( RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not stop tracing!'
ENDIF
C FLUSH THE MEMORY BUFFER TO DISK
CALL VT_TRC_FLUSH( RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not flush trace buffer!'
ENDIF
DO I = 1,COUNT
MSG_OUT(I) = TASKID
ENDDO
C RE-ENABLE TRACING. LEVEL 9 ASKS FOR EVERYTHING
C BUT ONLY EVENTS ENABLED BY THE COMMAND LINE OR
C ENVIRONMENT VARIABLE WILL BE RE-ENABLED)
CALL VT_TRC_START( 9, RC )
IF(RC .NE. 0) THEN
WRITE(6,*)'Could not restart tracing!'
ENDIF
IF( TASKID .GE. NUMTASK-1 ) THEN
DEST = 0
ELSE
DEST = TASKID + 1
ENDIF
CALL MPI_SEND(MSG_OUT, COUNT, MPI_INTEGER, DEST, 0,
+ MPI_COMM_WORLD, RC )
IF( TASKID .LE. 0 ) THEN
SRC = NUMTASK - 1
ELSE
SRC = TASKID - 1
ENDIF
CALL MPI_RECV(MSG_IN, COUNT, MPI_INTEGER, SRC, 0,
+ MPI_COMM_WORLD, RC)
CALL MPI_FINALIZE( RC )
STOP
END
C
Related Information
Functions:
For more information about VT tracing, see IBM Parallel Environment for AIX: Operation and Use, Volume 2.