STAF V3 Developer's Guide

Software Testing Automation Framework (STAF) V3 Developer's Guide

December 29, 2016

Version 3.4.26

Contents

  • Introduction
  • Obtaining the STAF Source Code
  • Requirements for Building STAF
  • Explaining the STAF Source Tree and Build Environment
  • Building STAF
  • Building STAF Core
  • Building OpenSSL (needed by the STAFTCP connection provider)
  • Building STAF IPv6 Support
  • Building STAF Java Support
  • Building STAF Perl Support
  • Building STAF Python Support
  • Building STAF Tcl Support
  • Building STAF Demo
  • Building Zip Service
  • Building STAF Ant Task
  • Building STAF Jython Support
  • Building STAF Documentation
  • Building STAF REXX Support
  • Building STAF Build Notes
  • Packaging STAF on Unix Machines
    •
  • Building External STAF Java Services
  • Building the STAX Service
  • Building the Event Service
  • Building the Cron Service
  • Building the EventManager Service
  • Building the HTTP Service
  • Building the Email Service
  • Building the Namespace Service
  • Building Other Java Services
    •
  • Running STAF from the Built Executables
  • Running on Unix
  • Running on Windows
  • Explaining how STAF is Packaged for Installation
  • STAF Design Documentation
  • STAF Coding Conventions
  • Reporting/Browsing/Fixing Bugs and Features
  • Debugging on Linux

  • Appendix A: Important Links
  • Appendix B: Common CVS Commands
  • Appendix C: New Developer Activities
  • Join the Open Source STAF Development Projects
  • Subscribe to Mailing Lists and Monitor Newsgroups
    •
  • Appendix D: Shutting Down STAF on Unix
    •

    Introduction

    This document explains how to build STAF. It assumes that you are familiar with the operating system(s) in question and the process of building software in general. It will walk you through the process of:

    1. Obtaining the STAF source code
    2. Setting up your build environment
    3. Building STAF
    4. Using the output of the build

    STAF developers are the intended audience for this document.

    Obtaining the STAF Source Code

    Externally open sourced STAF code is available on SourceForge via two methods:

    Obtaining STAF Source Code Via a Tar/Zip File

    Each tar/zip file contains a snapshot of the source code for a released version of STAF.

    1. Download the tar or zip file for the STAF Source Version you want from the STAF Sourceforge website (e.g. STAF344-src.tar.gz or STAF344-src.zip) from http://staf.sourceforge.net/getcurrent.php.

    2. If you downloaded the STAF source tar.gz file, you must uncompress and untar the file. For example: 
         gunzip STAF344-src.tar.gz
   tar -xvf STAF344-src.tar
    3. Or, if you downloaded the STAF source zip file, you must unzip the file (e.g. using WinZip, unzip, or the STAF ZIP service, etc.).

    Obtaining STAF Source Code Via CVS

    The current STAF code is contained in CVS, including code that has not been released yet.

    1. If on Windows:

      1. Open a Cygwin window. 

      2. cd /cygdrive/d

        where d is the drive where you want to put STAF code.

      3. md build

        where build is the name of the directory to where you are checking out STAF code. 

      4. cd build

    2. If on Unix:

      1. Log on as root 

      2. cd /

      3. mkdir build

        where build is the name of the directory to where you want to check out STAF code. 

    3. export CVS_RSH=ssh

      This must be done once for each window.

    4. The following command only needs to be done once per userid to set up your account. Change developername to your userid. 

      5. ssh developername@staf.sourceforge.net

      Enter your SourceForge password when prompted. Exit.

    5. The following command only needs to be done once per userid to create your home directory (e.g. /home/users/d/de/developername). Change developername to your userid. 

      6. ssh developername@cvs.staf.sourceforge.net

      Enter your SourceForge password when prompted. You cannot execute anything here so it will exit for you.

    6. The following command only needs to be done once per system to check out code. It specifies where the cvs root is, that you are doing a check out (co), and the directory (src) from the root of the code you are checking out. Change developername to your userid. 

      7. cvs -d :ext:developername@staf.cvs.sourceforge.net:/cvsroot/staf co src

      Enter your SourceForge password when prompted.
      Enter Yes if prompted to permanently add staf.cvs.sourceforge.net to the list of known hosts. 

    7. cd src/staf

    8. cvs update

      Enter your SourceForge password when prompted.
      Refer to the "Common CVS Commands" section for more information on "cvs update".

    Requirements for Building STAF

    To build STAF, you need to install the following software based on the operating system where you are building:

    To build the Java interface component of STAF and to build any STAF services written in Java, you need to install Java. Currently, we are mostly using Java 1.4.2 (IBM or Sun), but also support other versions of Java, including Java 1.5.0.

    To build the REXX interface component of STAF, you need to install REXX.

    Explaining the STAF Source Tree and Build Environment

    All STAF source code is contained in the /src/staf directory. This is the directory from which you run 'make' to build various STAF projects.

    The STAF uses the "whole-project makefile" approach described in Peter Miller's Recursive Make Considered Harmful article.

    The /src/staf/stafif directory contains STAF daemon and internal STAF Services source code.
    The /src/staf/stafproc directory contains STAF C interface library source code.
    The /src/staf/services directory contains source code for external STAF services like Log, Monitor, and Resource Pool.

    Any operating system specific code is contained in a subdirectory (e.g. win32, unix) under the STAF component.

    There are subdirectories for each language in which STAF services can be implemented in the /src/staf/lang directory.

    The STAF source tree looks like the following: 

    /src/staf/                       - Contains all STAF source code
/src/staf/makefile               - The master STAF makefile
/src/staf/build/                 - Contains auxilliary makefiles used in building STAF
/src/staf/codepage/              - Contains additional code pages
/src/staf/connproviders          - Contains source code for STAF connection providers
/src/staf/connproviders/localipc - Contains source code for the STAF Local IPC Connection Provier
/src/staf/connproviders/tcp      - Contains source code for the STAF TCP Connection Provider
/src/staf/docs/                  - Contains STAF documentation, including the makefile to build STAF docs
/src/staf/eclipse/               - Contains source code for STAF Eclipse plug-ins
/src/staf/History                - A file containing a history of changes made to STAF by version
/src/staf/install/               - Contains STAF installation source code
/src/staf/install/ia/            - Contains source code for installing STAF using InstallAnywhere (IA)
/src/staf/install/ismp/          - Contains source code for installing STAF using InstallShield
                                   Multi-Platform (ISMP) - Note this is no longer used as of STAF V3.3.0
/src/staf/install/unix/          - Contains the STAFInst program used to install from a STAF tar file
/src/staf/lang/                  - Contains source code for supporting the different languages in which
                                   STAF services can be implemented
/src/staf/lang/java/             - Contains source code for supporting STAF services implemented in Java
/src/staf/lang/jython/           - Contains source code for supporting STAF services that package Jython
/src/staf/lang/perl/             - Contains source code for supporting STAF services implemented in Perl
/src/staf/lang/ant/              - Contains source code for the STAF Ant Task
/src/staf/lang/rexx/             - Contains source code for supporting STAF services implemented in REXX
/src/staf/lang/tcl/              - Contains source code for supporting STAF services implemented in Tcl
/src/staf/lang/python/           - Contains source code for supporting STAF services implemented in Python
/src/staf/LICENSE.htm            - Contains the license for STAF
/src/staf/NOTICES.htm            - Contains notices about open source software packaged by STAF and
                                   their licenses
/src/staf/package/               - Contains makefiles used for packaging STAF
/src/staf/samples/               - Contains sample source code showing how to interact with STAF from
                                   different languages such as C, C++, and REXX
/src/staf/samples/demo/          - Contains the STAF Demo source code
/src/staf/serviceproxies/        - Contains source code for STAF service proxies
/src/staf/services/              - Contains source code for external STAF services like Log, Monitor, and
                                   Resource Pool, Zip, STAX, Event, EventManager, Cron, Email, etc
/src/staf/stafclnt/              - Contains STAF command line utility source code
/src/staf/stafif/                - Contains STAF C interface library source code
/src/staf/stafinfo/              - Contains the STAF information utility source code
/src/staf/stafproc/              - Contains STAF daemon and internal STAF Services source code
/src/staf/stafreg/               - Contains source code for the STAF Registration program
/src/staf/test/                  - Contains source code used to test STAF
/src/staf/utils/                 - Contains source code for STAF utilities like fmtlog (Format Log Utility)
/src/staf/webpages/sf/           - Contains source code for the STAF SourceForge web pages

    Building STAF

    This section describes how to build STAF from a valid source tree.

    Note: STAF's master makefile is located in the /src/staf directory. See it for additional information about the environment variables used.

    1. If on Windows, do the following steps in a Cygwin window.

    2. Check out the latest STAF source code (if not already checked out). Refer to the "Obtaining the STAF Source Code" section.

    3. cd /build/src/staf   (Assuming /build is the directory where you checked out STAF source code.)

    4. Set the appropriate environment variables:

      • OS_NAME - Set to the operating system where you are building STAF. Valid values for OS_NAME include:

        • win32
        • linux
        • linuxamd64
        • linuxia64
        • linux-ppc64-32
        • linux-ppc64-64
        • linux-ppc64le
        • zlinux
        • aix
        • aix433
        • aix64
        • hpux
        • solaris
        • zos
        • freebsd
        • freebsd410
        • macosx

      • BUILD_ARCH - Set to the architecture type being used.

        It is supported for the following operating systems:

        • hpux - Valid values are:

          • PA-RISC
            • - Specifies to build for HP-UX PA-RISC 32-bit. This is the default value if not specified.
          • PA-RISC64
            • - Specifies to build for HP-UX PA-RISC 64-bit.
          • IA64-32
            • - Specifies to build for HP-UX IA64 32-bit.
          • IA64-64
            • - Specifies to build for HP-UX IA64 64-bit.

        • solaris - Valid values are:

          • SPARC - Specifies to build for Solaris Sparc 32-bit. This is the default value if not specified.
          • SPARC64 - Specifies to build for Solaris Sparc 64-bit.
          • x64-64 - Specifies to build for Solaris AMD64 with 64-bit Java.

        • macosx

          • universal - Specifies to build for Mac OS X Universal binary with support for all architectures (OS X 10.10 or higher)

            • Note: If the BUILD_ARCH environment variable is not specified when building STAF for Mac OS X, it defaults to the architecture of the machine the build runs on.

        • zlinux

          • m31 - Specifies to build for zlinux 31-bit.

            • Note: If the BUILD_ARCH environment variable is not specified when building STAF for zlinux, it defaults to 64-bit

      • CC_TYPE - Set to the type of compiler being used. Currently, this is only supported for Windows builds. Valid values are:

        • MVC6 - Microsoft Visual C++ 6 (This is the default)
        • MVC7 - Microsoft Visual C++ 7 (also known as Microsoft Visual Studio.NET 2003)
        • MVC-SDK-IA64 - The IA-64 compiler shipped as part of the Microsoft Platform SDK (currently, we have only validated the compiler shipped as part of the February 2003 Platform SDK, but others may work)

      • MSVCDIR - If on Windows, set to the directory where you installed the Microsoft Visual C/C++ Compiler. For example: 

        • export MSVCDIR=c:/MVStudio

        Note: If a directory name where you installed your compiler contains spaces, you must use the short name instead (e.g. C:/PROGRA~1/MICROS~1 instead of C:/Program Files/Microsoft Visual Studio).

      • VSCOMMONDIR - If on Windows, set to the Microsoft Visual C++ Compiler's COMMON directory. For example: 

        • export VSCOMMONDIR=d:/MVStudio/Common

        Note: The VSCOMMONDIR environment variable is not needed if you selected the default install location for the common Microsoft Visual C++ components.

        Note: If a directory name where you installed your compiler contains spaces, you must use the short name instead (e.g. C:/PROGRA~1/MICROS~1/Common instead of C:/Program Files/Microsoft Visual Studio/Common).

      • MSSDKDIR - If on Windows, set to the directory in which you installed the Microsoft Platform SDK. For example, 

        • export MSSDKDIR=d:/MicrosoftSDK

        Note: MSSDKDIR only needs to be set if you are building IA-64 code for Windows. Typically, only MSSDKDIR or MSVCDIR (and, possibly, VSCOMMONDIR) need to be set. You don't normally need to set both.

        Note: If a directory name where you installed the Microsoft Platform SDK contains spaces, you must use the short name instead (e.g. C:/PROGRA~1/MICROS~2 instead of C:/Program Files/Microsoft SDK).

      • BUILD_TYPE - Set to either retail or debug.

      • PROJECTS - Set to the project(s) that you want to build. Valid projects are:

        • all - Builds all of the STAF projects
        • staf - Builds the STAF core code
        • connprov* - Builds the STAF TCP/IP V4 and Local connection providers
        • java - Builds the STAF Java Interface
        • perl - Builds the STAF Perl Interface
        • python - Builds the STAF Python Interface
        • tcl - Builds the STAF Tcl Interface
        • rexx - Builds the STAF Rexx Interface
        • docs - Builds the STAF documentation
        • demo - Builds the STAF Demo
        • jython - Builds the STAF Jython package that is packaged with some STAF services such as the STAX, EventManager, and Cron services
        • Plus many more (e.g. stax, event, cron, etc.)

        The PROJECTS environment variable can be set to any valid project or to multiple projects (in double quotes and separated by a space). For example:

           export PROJECTS=staf
   export PROJECTS="staf connprov* java docs"

      • If building the java project or a STAF service that is written in Java, the following environment variables must be set:

        • JAVA_DRIVE - If on Windows, set to drive where you installed Java
        • JAVA_LIBS - set to jvm
        • JAVA_VERSION - set to the version of Java use are using. For example, 1.4
        • JAVA_BUILD_V11 - set to 1 if using Java 1.1.x; otherwise set to 0. Note that STAF now requires Java 1.2 or later so the default for this environment variable is 0.
        • JAVA_BUILD_V12 - set to 1 if using Java 1.2 or later; otherwise set to 0. Note that STAF now requires Java 1.2 or later so the default for this environment variable is 1.
        • JAVA_V12_ROOT - set to the location where you installed Java. For example, on Windows, if Java is installed in D:\ibmjdk1.4.2, specify /cygdrive/d/ibmjdk1.4.2
        • JAVA_V12_LIBDIRS - set to the Java lib directory. For example on Windows, if Java is installed in D:\ibmjdk1.4.2, specify /cygdrive/d/ibmjdk1.4.2/lib

    5. To start the build, type: 

      6.   make

    You may want to put these commands in a shell script that you run instead, e.g. ". ./setstaf.sh".

    Building STAF Core

    Building OpenSSL

    To build STAF with OpenSSL support (e.g. to provide support for a secure TCP/IP interface and to provide the ability to get a checksum), you need to have OpenSSL binaries installed. If they are not already installed on your system, you'll have to build them. Download OpenSSL source code from the OpenSSL website and untar the OpenSSL tar file (e.g. openssl-1.0.2g.tar.gz) that you downloaded. Within IBM, need to use the OpenSSL source file available for download on iRAM.

    Starting with STAF V3.4.25, we use OpenSSL 1.0.2g when building the STAF binaries (previously we used OpenSSL 0.9.8e) so that we could change the STAF TCP/IP Connection Provider to use the TLS V1.2 protocol (instead of TLS V1.0 and disable other protocols (SSLv2, SSLv3, TLS V1.0, and TLS V1.1) to resolve OpenSSL POODLE vulnerabilities.

    OpenSSL provides instructions on how to build OpenSSL on Unix operating systems in the INSTALL file and for Windows in the INSTALL.W32 and INSTALL.W64 files.

    Following is how we built OpenSSL on various operating systems.

    Building STAF IPv6 Support

    Building STAF Java Support

    Building STAF Perl Support

    Building STAF Python Support

    Building STAF Tcl Support

    Building STAF Demo

    Building Zip Service

    Notes:

    Building STAF Ant Task

    Notes:

    Building STAF Jython Support

    Building STAF Documentation

    Notes:

    Building STAF REXX Support

    Note that you need to have RXPP installed in order to build the STAF Documentation. On Windows, you should download the rxpp.tar file (available for IBM Austin STAF developers on our STAF ftp server in the /tools directory)) to d:/tools/rxpp, and untar the file in this directory.

    STAF Build Notes

    On Solaris, there is an additional file that is not built with STAF but must be included in the lib directory. The file should already reside on your build system, so simply copy this file to the lib directory before packaging the build for distribution. The file is:

    Note that on Solaris, even if you build a retail version of STAF, the binary and library files will still contain symbolic information. After the build completes, you must run the "strip" command on every binary and library file before packaging the build for distribution.

    Note that on AIX, you may receive the following error message when building STAF: 

        xlC_r: 1501-230 Internal Compiler error; Please contact your Service Representative

    If you receive this error message, ignore it (it is a compiler bug on AIX) and re-start the build (by typing "make" again). The second make should be successful.

    To run using the version of STAF you just built, refer to the "Running STAF from the Built Executables" section.

    Packaging STAF on Unix Machines

    Building External STAF Java Services

    We deliver external STAF services written in Java in their own zip/tar files that contain the service jar file, service documentation, etc. This section provides instructions on how to build the various STAF Java services.

    Building the STAX Service

    Notes:

    Building the Event Service

    Building the Cron Service

    Building the EventManager Service

    Building the HTTP Service

    Notes:

    Building the Email Service

    Notes:

    Building the Namespace Service

    Notes:

    Building Other Java Services

    Running STAF from the Built Executables

    To run STAF from the executables you built, perform the following based on the operating system you are using:

    Running on Unix

    1. If STAF is already running, shut it down: 

      2. STAF local SHUTDOWN SHUTDOWN

    2. Change the environment settings to use the STAF directories you just built. For example, on Linux, do: 

      3. cd /build/rel/linux/staf/retail   (or /build/rel/linux/staf/debug)
export STAFHome=$PWD
export LD_LIBRARY_PATH=$STAFHome/lib:$STAFHome/lib/java12:$LD_LIBRARY_PATH
export PATH=$STAFHome/bin:$PATH
export STAFCONVDIR=$STAFHome/codepage

    3. Set up the STAF configuration file that you want to use. If you already have one set up where STAF was installed, you can copy it. For example: 

      4. cp /usr/local/staf/bin/STAF.cfg bin

    4. Make sure you are now using version of STAF that you just build: 

      5. which STAFProc

      should show something like: /build/rel/linux/staf/retail/bin/STAFProc

    5. Start STAF: 

      6. STAFProc &

      If you get error "mprotect reset:Bad address", then check the version (uname -a), and if 2.4, type the following and then restart STAF: 

      export LD_ASSUME_KERNEL=2.2.25

    Running on Windows

    You can run STAF from the executables you built from a Cygwin window or from a Windows command prompt.

    Running in a Windows Command Prompt Window

    1. If STAF is already running, shut it down: 

      2. STAF local SHUTDOWN SHUTDOWN

    2. Change the environment settings to use the STAF retail (or debug) directories you just built. For example, if you built a retail version of STAF in directory D:\build, do: 

      3.   D:
  cd \build\rel\win32\staf\retail   (or \build\rel\win32\staf\debug)
  set STAFHome=D:\build\rel\win32\staf\retail
  set PATH=%STAFHome%\bin;%STAFHome%\lib;%STAFHome%\lib\java12;%PATH%
  set STAFCONVDIR=%STAFHome%\codepage
    3. Set up the STAF configuration file that you want to use (in directory D:\build\rel\win32\staf\retail\bin). If you already have one set up where STAF was installed, you can copy it. For example: 

      4. cp C:\STAF\bin\STAF.cfg D:\build\rel\win32\staf\retail\bin

    4. Make sure you are now using version of STAF that you just build: 

      5. which STAFProc

      Note: The "which" utility for Windows does not come with Windows. Should show something like: d:\build\rel\win32\staf\retail\bin/STAFProc.exe.

    5. Start STAF: 

      6. STAFProc

    Running in a Cygwin Window

    1. If STAF is already running, shut it down: 

      2. STAF local SHUTDOWN SHUTDOWN

    2. Change the environment settings to use the STAF retail (or debug) directories you just built. For example, if you built a retail version of STAF in directory D:\build, do: 

      3.   cd /cygdrive/d/build/rel/win32/staf/retail   (or /cygdrive/d/build/rel/win32/staf/debug)
  export STAFHome=$PWD
  export PATH=$STAFHome/bin:$STAFHome/lib:$STAFHome/lib/java12:$PATH
  export STAFCONVDIR=d:/build/rel/win32/staf/retail/codepage
    3. Set up the STAF configuration file that you want to use (in directory /cygdrive/d/build/rel/win32/staf/retail/bin). If you already have one set up where STAF was installed, you can copy it. For example: 

      4. cp /cygdrive/c/STAF/bin/STAF.cfg /cygdrive/d/build/rel/win32/staf/retail/bin/STAF.cfg

    4. Make sure you are now using version of STAF that you just build: 

      5. type STAFProc

      Should show something like: 

      STAFProc is /cygdrive/d/build/rel/win32/staf/retail/bin/STAFProc

    5. Start STAF: 

      6. STAFProc

    Explaining How STAF is Packaged for Installation

    STAF is packaged for installation using InstallAnywhere for most operating systems and/or as GNU zipped tar files for some of the Unix operating systems.

    STAF Design Documentation

    When adding a features to STAF, provide a design document in the docs/features directory in CVS. The feature design should be sent to the entire STAF development team to be reviewed before implementation.

    The template to use when creating a feature design document is docs/features/Feature_nnnnnn.txt. The naming convention for a design document is Feature_nnnnnn.txt where you replace nnnnnn with the actual feature number.

    The feature design template contains: 

     
    Feature ID  : nnnnnn
    Response Due: mm/dd/yyyy
    Title       : Add info on which interfaces are enabled
     
     
    Description
    -----------
     
     
     
    Problem(s) Solved
    -----------------
     
     
     
    Related Features
    ----------------
     
     
     
    External Changes
    ----------------
     
     
     
    Internal Changes
    ----------------
     
     
     
    Design Considerations
    ---------------------
     
     
     
    Backward Compatibility Issues
    -----------------------------
     
     
     

    STAF Coding Conventions

    STAF provides consistent and easily readable source code by adhering to the following conventions:

    1. Use Unix (\n) end of line characters. Developers will be editing the source code on a variety of platforms with a variety of editors. The Unix EOL character is universal, windows EOL (\r\n) are not. STAF FS service provides a command to convert EOL characters. This can be used to convert the files you edit if your editor automatically uses native EOL and not Unix EOL.

    2. Keep all lines at 80 or less. Some editors (EMACS) only show 80 chars wide.

    3. Don't use tab. The \t converts to a different number of spaces in different environments. The indent convention is 4 spaces. If you use tabs make sure they are converted to spaces.

    4. Open and close all blocks on their own line '{' and '}' should be alone on the lines where they occur. For example:

      5.     try
    {
        connection->writeUInt(0);
    }
      Not: 

          try{ connection->writeUInt(0); }
    5. Horizontal white space is your friend.

      1. Separate arguments in function calls and declarations.

        2. void rollBuffer(char * buffer, int bufferLen, int rollLen)

      2. Separate operators from the arguments.

        3. int endIndx = bufferLen - rollLen;

      3. Separate comparators from the arguments.

        4. if ((i == offset) || (last == -1))

    6. Vertical white space is your friend.

      1. Separate variable declarations.
      2. Separate clauses (if/while/for)
      3. Separate comments
      4. Separate logically independent sections of code
      5. Separate functions

    7. Comments make life easier for the next person. Accurate and informative comments allow other people to understand and modify your code. It allows for easy identification of the pertinent section of code that needs to be edited.

      1. Comment function declarations. Tell what the function does and the effect of all arguments

        2.    /***********************************************************************/
   /* STAFStringNumOfWords - Returns the number of words in a STAFString  */
   /*                                                                     */
   /* Accepts: (In)  A STAFString_t                                       */
   /*          (Out) The number of words                                  */
   /*          (Out) A pointer to an OS return code (may be NULL)         */
   /*                                                                     */
   /* Returns: kSTAFOk on success                                         */
   /*          other on error                                             */
   /***********************************************************************/
      2. Comment blocks of code. Allow editors to easily identify which block is relevant to them 

        3.    /* This clause establishes the new eol marker.
      It causes the use of binary transfer if the eol on both sides
      are the same and no codepage conversion is to be done.
      This allows for a faster transfer.    */
      3. Comment confusing statements. Allow editors to understand what and why things are happening.

        4.    // offset = buffer length - null char - ending index of eol
   offset = len - 1 - endBuffer;
    8. Use self documenting code. Highly descriptive variable names and indentation make code legible, making the need for comments lower.

    9. Naming convention:

      1. Class names: Starts with "STAF" 1st letter of each word uppercase, no - or _, remaining letters lower-case. 

        class STAFHandleManager

      2. Variables: Lowercase, no - or _, 1st word all lower-case, subsequent words 1st letter uppercase 

        3. unsigned int maxConvertedLength;

      3. Function declarations: variable naming convention 

        4. void rollBuffer(char * buffer, int bufferLen, int rollLen)

      4. Enumerations: 1st letter k, variable naming convention 

        5. enum IndexRep { kChar = 0, kByte = 1 };

    10. Use simple code. The simpler the code the easier it is to maintain.

    Reporting/Browsing/Fixing Bugs and Features

    All bug reports and feature requests for STAF are kept on SourceForge.

    When you begin work on a bug or feature, set the "Assigned to" field to your userid. Make the changes and test them. Update the history file to describe the new feature or bug fix you made, making sure you reference the request ID. Commit your changes into CVS, specifying the request ID in the commit message. Then update the bug/feature, adding comments on the changes you made, specify the Resolution and Status, and submit your changes.

    Debugging on Linux

    On Linux systems, you can use gdb to debug STAF, usually with more success using a debug version of STAF. Using gdb can be useful when a SIGSEGV problem is occurring.

    Use gdb to debug STAF locally as follows:

    1. gdb STAFProc
    2. run
    3. Recreate the problem.

    Use gdb to debug STAF remotely as follows:

    1. You need to establish two telnet sessions to the system to be debugged.

    2. From one telnet session, type: 

      3.       gdb STAFProc
      run
    3. From the other telnet session, recreate the problem.

    Various commands that you might need while using gdb are:

    Appendix A: Important Links

    Here are some commonly used links for STAF:

    Appendix B: Common CVS Commands

    Here are some of the common CVS commands that you will use. Use the 'man cvs' command to get more information about these CVS commands and others. 

    ·                cvs update

    Compares your directory tree with the tree in the CVS repository, by file, based on the directory that you are currently in. Execute this command from within your private source directory when you wish to update your copies of source files from changes that other developers have made to the source in the CVS repository. A -d option can be used to add any new directories. Each file that has changed will have one of the following codes which indicate how it was changed: 

    ·                cvs add file...

    Add a new file or directory to the CVS repository, pending a 'cvs commit' on the same file. Can only be done from within sources created by a previous 'cvs checkout' invocation. (Does not directory affect repository; changes working directory.)

    Note that if you are checking in a binary file (such as a gif or pdf file), you must add the -kb option to the add command. This indicates that the file is a binary file. This is important so that when updates are made to the file, cvs will not attempt to "merge" the 2 versions of the binary file, which may cause bad things to happen. 

    ·                cvs checkout

    Make a working directory of source files for editing. (Creates or changes working directory.) This is a necessary preliminary for most cvs work: creates your private copy of the source. You can also use a path relative to the source respository here. You can work with this copy without interfering with others' work. At least one subdirectory level is always created. 

    ·                cvs diff

    Show differences between files in working directory and source repository, or between two revisions in source repository. (Does not change either repository or working directory.) Used to show the code changes. < in front of lines of code indicate that these lines have been removed and > in front of lines of code indicate that these lines have been added. 

    ·                cvs commit -m "Enter a message here that describes the change including the bug/feature ID (#0123456)"

    Apply to the source repository changes, additions, and deletions from your working directory. (Changes repository.) Use this command when you wish to 'publish' your changes to other developers, by incorporating them in the source repository. 

    ·                cvs log

    Display log information. (Does not change repository or working directory.) 

    ·                cvs remove file...

    Use this command (after erasing any files listed)

    To list all of the CVS commands, type: 

    cvs help

    To get help for a specific CVS command, for example update, type: 

    cvs --help update

    Appendix C: New Developer Activities

    When a new developer joins the STAF team, he/she must perform the following activities.

    Join the Open Source STAF Development Project

    1. First read the IBM Open Source Guidelines at http://ltc.linux.ibm.com/open_source.
    2. Get an approval note from your manager saying that you can participate in the External Open Source STAF Project (and send David Bender a copy of this note).
    3. Register with SourceForge at:
    4. Let another STAF Developer know your userid so they can add you as a developer for the projects.
    5. Get with another STAF Developer to help you get your office machine set up to download the code and build it.

    Subscribe to Mailing Lists and Monitor Newsgroups

    External and internal STAF customers can send questions to the STAF SourceForge mailing lists and forums, and internal IBM STAF customers can post questions on the AWE Newsgroup. Part of the job responsibilities of a STAF Developer is to monitor the newsgroups, the SourceForge Mailing Lists, and the SourceForge Forums and respond to any questions or support requests. STAF developers get notes sent to them when anyone sends a note to one of the mailing lists or posts a message on a forum. However, STAF developers must monitor the Newsgroups to check for any new postings.

    1. Subscribe to the three STAF SourceForge mailing lists. Click on the links below to signup for a list, to post a message, to view archived messages, or to change your subscription. We try to respond to any questions within a couple of hours during normal business hours.
      • staf-news - is a moderated, low-traffic list which carries only periodic announcements of STAF releases and important updates.
      • staf-users - is the list for questions, suggestions, support, and general discussion of STAF.
      • staf-devel - is the list for STAF developers only.
    2. Add the following IBM STAF newsgroup to your browser. You can click on the link below to access the newsgroup:
    3. Subscribe to the SourceForge staf-dev-bugs mailing list. We use this private mailing list to mirror incoming bugs and feature requests for STAF.

    Appendix D: Shutting Down STAF on Unix

    Currently, there is a bug that occurs sometimes where STAF cannot be restarted after shutting it down via "STAF LOCAL SHUTDOWN SHUTDOWN". If this happens, perform the following: 

    killall -9 STAFProc
    ps -ea | grep STAF
    2.                 kill -9

    Replace with STAF's pid. 

    ps -ea | grep STAF

    End Of Document

    This is the end of the document.