Studio:Log.pm

This package provides standard multi-output logging functionality for all STRIDE perl scripts.

Example

use strict;
use warnings;
use Carp;
use Win32::TieRegistry(Delimiter=>"/");
use File::Spec;
use Time::HiRes qw (usleep gettimeofday tv_interval sleep);
use Win32::OLE;
Win32::OLE->Option(Warn => 3);

# setup the lib path
use vars qw(
    $studio
    $testSuite
    $ascript
    $StrideDir
    $StrideLibDir
);
BEGIN {
    $StrideDir = 
        $Registry->{"LMachine/SOFTWARE/S2 Technologies/STRIDE/InstallDir"} ||
        $ENV{'STRIDE_DIR'} ||
        'C:\\STRIDE';
    $StrideLibDir = File::Spec->catdir($StrideDir, 'lib', 'perl');
}

###############################
# Imported Libs 
###############################
use lib $StrideLibDir; # Use the above calculated path to finf the lib's

use S2S::Log;

 
# create a test case to which comments will be added
$main::testSuite->Tests->RemoveAll();
my $tcName = "Sample Test Case";
my $tc = $main::testSuite->Tests->Add($tcName);

my $logMsg = $main::ascript->Messages->Item("logMSG")->Owner;

# set up a trace view to capture broadcast log messages
my $tvName = 'Log Viewer';
my $tv = $main::studio->Workspace->TraceViews->Item($tvName);
if (!$tv) {
    $tv = $main::studio->Workspace->TraceViews->Add("HostTraceView");
    $tv->{Name} = $tvName;
}
$tv->Open();
my $tvFilter =$tv->Filters->InterfacesByUniqueId->Item($logMsg->Name);
$tvFilter->{Data} = 1;
$tvFilter->{On} = 1;
$tv->Filters->InterfacesByUniqueId->Apply();


my $log = new Log;

$log->addStudio(
    {
        # accept defaults
    }
);

$log->addFile(
   {
      # accept defaults
   }
);

$log->addBCMessage(
    {
        messageOwner => $logMsg
    }
);

$log->addTestCase(
    {
        testCase => $tc
    }
); 

$log->addAnnotation(
    {
        testSuite => $main::testSuite
    }
);

$log->debug('this is a debug test message');
$log->warning('this is a warning test message');
$log->error('this is an error test message');
$log->fatal('this is a fatal test message');

my $number = 12345;

$log->debug('this is another debug test message: %x and %e ', $number, $number);
$log->warning('this is another warning test message');
$log->error('this is another error test message');
$log->fatal('this is another fatal test message');

$tc->{Status} = "PASS";

Example .h File to Define Broadcast Message Output

#include <sr.h>

#ifdef _UNICODE
typedef short TCHAR;
#else
typedef char TCHAR ;
#endif

#define logMSG 11758 | srMT_BRD
#define MAX_LOGMSG 256

typedef struct
{
    TCHAR* pMsg;
}LOGMSG_t;

#ifdef _SCL
#pragma scl_msg(logMSG, LOGMSG_t)
#pragma scl_string(LOGMSG_t.pMsg, MAX_LOGMSG)
#endif /* _SCL */

---

<?xml version="1.0" ?>

• NAME
• SYNOPSYS
• DESCRIPTION
• EXAMPLE
• FUNCTIONS

NAME

S2S::Log - mutli-output logging object

SYNOPSYS

use S2S::Log;

DESCRIPTION

This module is used for all logging from STRIDE.

The module allows logging to one or many output locations at once. The supported output locations are as follows:

• The STRIDE Studio message window
• A disk file
• A testcase comment
• A testsuite annotation
• A broadcast message

Message Levels

You assign a level to each message you log. This provides a simple filtering mechanism as each output can optionally be configured to log only those messages that exceed a specified level.

For example, you might want to log only ERROR and FATAL messages to the STRIDE Studio message window, thus ignoring DEBUG and WARNING messages.

From lowest to highest, the module defines the following levels:

• DEBUG
• WARNING
• ERROR
• FATAL

To use the module, you do the following:

1. Create an instance of the S2S::Log object
2. Add the outputs that you want; you typically supply operational parameters to customize the outputs as well.
3. Write log messages to the log object

Note

This module derives from from Log::Handler. If you need advanced functionality, please see [[1]]

EXAMPLE

use strict;
use warnings;
use Carp;
use Win32::TieRegistry(Delimiter=>"/");
use File::Spec;
use Time::HiRes qw (usleep gettimeofday tv_interval sleep);
use Win32::OLE;
Win32::OLE->Option(Warn => 3);# setup the lib path
use vars qw(
    $studio
    $testSuite
    $ascript
    $StrideDir
    $StrideLibDir
);
BEGIN {
    $StrideDir = 
        $Registry->{"LMachine/SOFTWARE/S2 Technologies/STRIDE/InstallDir"} ||
        $ENV{'STRIDE_DIR'} ||
        'C:\\STRIDE';
    $StrideLibDir = File::Spec->catdir($StrideDir, 'lib', 'perl');
}###############################
# Imported Libs 
###############################
use lib $StrideLibDir; # Use the above calculated path to finf the lib'suse S2S::Log; 
# create a test case to which comments will be added
$main::testSuite->Tests->RemoveAll();
my $tcName = "Sample Test Case";
my $tc = $main::testSuite->Tests->Add($tcName);my $logMsg = $main::ascript->Messages->Item("logMSG")->Owner;# set up a trace view to capture broadcast log messages
my $tvName = 'Log Viewer';
my $tv = $main::studio->Workspace->TraceViews->Item($tvName);
if (!$tv) {
    $tv = $main::studio->Workspace->TraceViews->Add("HostTraceView");
    $tv->{Name} = $tvName;
}
$tv->Open();
my $tvFilter =$tv->Filters->InterfacesByUniqueId->Item($logMsg->Name);
$tvFilter->{Data} = 1;
$tvFilter->{On} = 1;
$tv->Filters->InterfacesByUniqueId->Apply();my $log = new Log;$log->addStudio(
    {
        # accept defaults
    }
);$log->addFile(
   {
      # accept defaults
   }
);$log->addBCMessage(
    {
        messageOwner => $logMsg
    }
);$log->addTestCase(
    {
        testCase => $tc
    }
);$log->addAnnotation(
    {
        testSuite => $main::testSuite
    }
);$log->debug('this is a debug test message');
$log->warning('this is a warning test message');
$log->error('this is an error test message');
$log->fatal('this is a fatal test message');my $number = 12345;$log->debug('this is another debug test message: %x and %e ', $number, $number);
$log->warning('this is another warning test message');
$log->error('this is another error test message');
$log->fatal('this is another fatal test message');$tc->{Status} = "PASS";

FUNCTIONS

new()

Creates and returns an instance of the logger.

my $log = new S2S::Log;

addStudio()

Adds the STRIDE Studio message window as an output of this logger.

$log->addStudio({level => 'error'});

 [[arg1: $params (optional)]]  

An anonymous hash; string values at keys are as follows:

  [[level key:]]  

Determines minimum logging level for this output. Valid values are 'debug', 'warning', 'error', and 'fatal'.

Defaults to 'debug' if omitted (all messages logged).

addFile()

Adds a disk file as an output of this logger.

$log->addFile({level => 'error', filename => 'C:\\myLog\\mylog.txt'});

 arg1: $params (optional)  

An anonymous hash; string values at keys are as follows:

  [[level key:]]  

Determines minimum logging level for this output. Valid values are 'debug', 'warning', 'error', and 'fatal'.

Defaults to 'debug' if omitted (all messages logged).

  [[filename key:]]  

Sets the output filename for this output. A complete path is required. If the specified folder does not exist, it is created. If the output file already exists, subsequent output is appended..

Defaults to %WORKSPACE_DIR%\output.log if omitted.

addBCMessage()

Adds a STRIDE broadcast message as an output of this logger.

   # a broadcast message has been captured with the name 'logMSG'
   my $logMsg = $main::ascript-EMessages-EItem("logMSG")-EOwner;
   $log-EaddBCMessage({level =E 'error', messageOwner =E $logMSG});

arg1: $params (NOT optional; the messageOwner must be specified)  

An anonymous hash; string values at keys are as follows:

  [[level key:]]  

Determines minimum logging level for this output. Valid values are 'debug', 'warning', 'error', and 'fatal'.

Defaults to 'debug' if omitted (all messages logged).

  [[messageOwner key:]]  

Sets the broadcast message owner for this output. An instance of a message owner object is required.

The broadcast message must have a payload member named pMsg to which the message string is written..

For example:

        #include 
        
        #ifdef _UNICODE
        typedef short TCHAR;
        #else
        typedef char TCHAR ;
        #endif
        
        #define logMSG 11758 | srMT_BRD
        #define MAX_LOGMSG 256
        
        typedef struct
        {
            TCHAR* pMsg;
        }LOGMSG_t;
        
        #ifdef _SCL
        #pragma scl_msg(logMSG, LOGMSG_t)
        #pragma scl_string(LOGMSG_t.pMsg, MAX_LOGMSG)
        #endif /* _SCL */

addTestCase()

Adds a STRIDE test case as an output of this logger.

    # $tc is the test case to be logged to
    $log-EaddTestCast({level =E 'error', testCase =E $tc});>

arg1: $params (NOT optional; testCase must be specified)  

An anonymous hash; string values at keys are as follows:

  [[level key:]]  

Determines minimum logging level for this output. Valid values are 'debug', 'warning', 'error', and 'fatal'.

Defaults to 'debug' if omitted (all messages logged).

  [[testCase key:]]  

Sets the output test case for this output. Logged messages are added as comments to the specified test case. The comment label is set to: "[LEVEL] Log Message" where LEVEL is one of: DEBUG, WARNING, ERROR, FATAL.

addAnnotation()

Adds a STRIDE test suite annotation as an output of this logger.

    # $ts is the test suite to be logged to
    $log-EaddAnnotation({level =E 'error', testSuite =E $ts});>

arg1: $params (NOT optional; testSuite must be specified)  

An anonymous hash; string values at keys are as follows:

  [[level key:]]  

Determines minimum logging level for this output. Valid values are 'debug', 'warning', 'error', and 'fatal'.

Defaults to 'debug' if omitted (all messages logged).

  [[testSuite key:]]  

Sets the output test suite for this output. Logged messages are added as comments to the suite's annotation with the name "[LEVEL] Log Message", where LEVEL is one of DEBUG, WARNING, ERROR, FATAL.

If the annotation does not exist, then it is created on first write. Upon creation, the comment label is set to: "[LEVEL] Log Message" (where LEVEL is one of: DEBUG, WARNING, ERROR, FATAL) and the annotation level is set to correspond to the level indicated in the label (note that WARNING is mapped to the *warn* level.).

    # $tc is the test case to be logged to
    $log-Edebug("this is a debug message");
    my $number = 32767;
    $log-Edebug("you can also use sprintf: %x %e ", $number, $number); 

[[arg1: $msg]]  

String to be logged.

Note that the argument(s) you supply here are passed to sprintf, so you can supply arguments as FORMAT, LIST if desired. (Useful for number formatting, changing radix, etc.) See [[2]]

warning()

Writes a log message with the WARNING level to all added outputs..

    # $tc is the test case to be logged to
    $log-Ewarning("this is a debug message");
    my $number = 32767;
    $log-Ewarning("you can also use sprintf: %x %e ", $number, $number); 

[[arg1: $msg]]  

String to be logged.

Note that the argument(s) you supply here are passed to sprintf, so you can supply arguments as FORMAT, LIST if desired. (Useful for number formatting, changing radix, etc.) See [[3]]

error()

Writes a log message with the ERROR level to all added outputs..

    # $tc is the test case to be logged to
    $log-Eerror("this is a debug message");
    my $number = 32767;
    $log-Eerror("you can also use sprintf: %x %e ", $number, $number); 

[[arg1: $msg]]  

String to be logged.

Note that the argument(s) you supply here are passed to sprintf, so you can supply arguments as FORMAT, LIST if desired. (Useful for number formatting, changing radix, etc.) See [[4]]

fatal()

Writes a log message with the FATAL level to all added outputs..

    # $tc is the test case to be logged to
    $log-Efatal("this is a debug message");
    my $number = 32767;
    $log-Efatal("you can also use sprintf: %x %e ", $number, $number); 

[[arg1: $msg]]  

String to be logged.

Note that the argument(s) you supply here are passed to sprintf, so you can supply arguments as FORMAT, LIST if desired. (Useful for number formatting, changing radix, etc.) See [[5]]