Exacct::Catalog(3PERL)					      Perl Library Functions					    Exacct::Catalog(3PERL)

NAME

       Exacct::Catalog - exacct catalog tag manipulation

SYNOPSIS

       use Sun::Solaris::Exacct::Catalog qw(:ALL);
       my $ea_cat = Sun::Solaris::Exacct::Catalog->new(
	   &EXT_UINT64 | &EXC_DEFAULT | &EXD_PROC_PID);

DESCRIPTION

       This  class  provides  a  wrapper around the 32-bit integer used as a catalog tag.  The catalog tag is represented as a Perl object blessed
       into the Sun::Solaris::Exacct::Catalog class so that methods can be used to manipulate fields in a catalog tag.

   Constants
       All the EXT_*, EXC_*, and EXD_* macros are provided as constants.  Constants passed to the methods below can either be  the  integer  value
       such as EXT_UINT8 or the string representation such as  "EXT_UINT8".

   Functions
       None.

   Class methods
       register($cat_pfx, $catalog_id, $export, @idlist)

	   This   method   is	used   to   register   application-defined   libexacct(3LIB)   catalogs   with	 the   exacct  Perl  library.  See
	   </usr/include/sys/exacct_catalog.h> for details of the catalog tag format.  This method allows symbolic names and strings  to  be  used
	   for manipulating application-defined catalogs. The first two parameters define the catalog prefix and associated numeric catalog ID. If
	   the $export parameter is true, the constants are exported into the caller's package. The final parameter is a list of (id, name)  pairs
	   that identify the required constants. The constants created by this method are formed by appending $cat_pfx and "_" to each name in the
	   list, replacing any spaces with underscore characters and converting the resulting string to uppercase  characters.	The  $catalog_name
	   value  is  also  created  as  a constant by prefixing it with EXC_ and converting it to uppercase characters. Its value becomes that of
	   $catalog_id shifted left by 24 bits. For example, the following call:

	     Sun::Solaris::Exacct::Catalog->ea_register("MYCAT", 0x01, 1,
		FIRST => 0x00000001, SECOND => 0x00000010);

	   results in the definition of the following constants:

	     EXC_MYCAT	  0x01 << 24
	     MYCAT_FIRST  0x00000001
	     MYCAT_SECOND 0x00000010

	   Only the catalog ID value of 0x01 is available for application use (EXC_LOCAL). All other values are reserved.  While it is possible to
	   use values other than 0x01, they might conflict with future extensions to the libexacct file format.

	   If any errors are detected during this method, a string is returned containing the appropriate error message. If the call is sucessful,
	   undef is returned.

       new($integer)
       new($cat_obj)
       new($type, $catalog, $id)

	   This method creates and returns a new Catalog object, which is a wrapper around a 32-bit integer catalog tag. Three	possible  argument
	   lists  can be given. The first variant is to pass an integer formed by bitwise-inclusive OR of the appropriate EX[TCD]_* constants. The
	   second variant is to pass an existing Catalog object that will be copied. The final variant is to pass in  the  type,  catalog  and	ID
	   fields  as separate values. Each of these values can be either an appropriate integer constant or the string representation of the con-
	   stant.

   Object methods
       value()		This method allows the value of the catalog tag to be queried. In a scalar context it returns the  32-bit  integer  repre-
			senting  the  tag. In a list context it returns a (type, catalog, id) triplet, where each member of the triplet is a dual-
			typed scalar.

       type()		This method returns the type field of the catalog tag as a dual-typed scalar.

       catalog()	This method returns the catalog field of the catalog tag as a dual-typed scalar.

       id()		This method returns the id field of the catalog tag as a dual-typed scalar.

       type_str()	These methods return string representations of the appropriate value. These methods can be used for textual output of  the
       catalog_str()	various catalog fields. The string representations of the constants are formed by removing the EXT_, EXC_, or EXD_ prefix,
       id_str() 	replacing any underscore characters with spaces, and converting the remaining string to lowercase characters.

   Exports
       By default nothing is exported from this module. The following tags can be used to selectively import constants and  functions  defined	in
       this module:

       :CONSTANTS    EXT_*, EXC_*, and EXD_*

       :ALL	     :CONSTANTS

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWpl5u			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       Exacct(3PERL),  Exacct::File(3PERL),  Exacct::Object(3PERL),  Exacct::Object::Group(3PERL),  Exacct::Object::Item(3PERL),  libexacct(3LIB),
       attributes(5)

SunOS 5.11							    1 Dec 2002						    Exacct::Catalog(3PERL)