head	1.4;
access;
symbols;
locks
	mohlerb:1.4; strict;
comment	@# @;


1.4
date	99.06.17.16.59.19;	author mohlerb;	state Exp;
branches;
next	1.3;

1.3
date	99.06.15.00.05.28;	author mohlerb;	state Exp;
branches;
next	1.2;

1.2
date	99.06.14.23.58.16;	author mohlerb;	state Exp;
branches;
next	1.1;

1.1
date	99.06.09.01.44.34;	author mohlerb;	state Exp;
branches;
next	;


desc
@Programming standards for extending OS modules
@


1.4
log
@added indentation standard
@
text
@PROGRAMMING STANDARDS

$Header: /export/home/mohlerb/src/perl/syssumm/RCS/PROGRAMMING_STDS,v 1.3 1999/06/15 00:05:28 mohlerb Exp mohlerb $

$Revision: 1.3 $

$Log: PROGRAMMING_STDS,v $
Revision 1.3  1999/06/15 00:05:28  mohlerb
added "Handling Different Versions of the Same Operating System" section

Revision 1.2  1999/06/14 23:58:16  mohlerb
Added "Return Values from Functions" section

Revision 1.1  1999/06/09 01:44:34  mohlerb
Initial revision


The following areas are currently defined:

	*  Minimum Requirements

	*  Clever code vs. Maintainable code
	*  Config files vs. Running Processes
	*  Handling Different Versions of the Same Operating System
	*  Indentation
	*  Mailing Output
	*  Megabytes
	*  Return Values from Functions
	*  RunAsRoot


Minimum Requirements
-------------------

Remember the minimum requirements for the OS modules and
for the code which runs on the remote system to collect
the profile information.  From the README:

On the remote systems the only requirement is Perl 5.x.  No
additional CPAN Perl modules are required to run the profiling
script.


Clever code vs. Maintainable code
---------------------------------

If as a syssumm developer you have to choose between some
really, really clever (but unreadable) Perl code and code
that the average Perl programmer can understand and maintain,
please choose the maintainable code.


Config files vs. Running Processes
----------------------------------

In order to determine whether a particular software process is 
configured and/or running: first check the configuration file to 
see whether it is configured in the "standard" way.  If it is
not configured, still check to see whether the process is being
started from some sort of local "hack".  Return whether the software
is running and whether the configuration is "standard" or "local".

	Software:RunningSendmail:Unknown
	Software:RunningSendmail:No
	Software:RunningSendmail:Yes, standard configuration
	Software:RunningSendmail:Yes, local configuration 


Handling Different Versions of the Same Operating System
--------------------------------------------------------

Sometimes you need to be able to handle device names or program
output differently between different versions of the same operating
system.  This is true for HP-UX (especially between versions 9 and
higher).

First, you can plug version specific function names into the
Routines hash.  First, make sure that you define $OSVersionMajor.
Next, define the name of the subroutine, then stuff it into the
Routines hash like this:

	my $ReturnProcessorsHPUX = "ReturnProcessorsHPUX$OSVersionMajor";
	$main::Routines{Hardware}{Processors} = \&$ReturnProcessorsHPUX;

Next, have a different version of the ReturnProcessors routine for 
each major OS version.  Note that for HP-UX, 10 and 11 are the same.

	sub ReturnProcessorsHPUX09 ($)
	{
		...
	}


	sub ReturnProcessorsHPUX10 ($)
	{
		...
	}


	sub ReturnProcessorsHPUX11 ($)
	{
		...
		return ReturnProcessorsHPUX10($Subcategory);
	}


Indentation
-----------

Please adhere to using physical tabs in ASCII text that are
8 character position to the tab stop.


Mailing Output
--------------

syssumm needs to know what command to use to send e-mail.  Under
Solaris and HP-UX it can use mailx since it defines a "-s" command
line argument for supplying a "Subject:" line.  On these systems
the mail command doesn't support "-s".  Under Linux, the mail
command has "-s" and there is no mailx command.

In syssumm, a variable called $MailCommand is defined.  It defaults
to "".  In common.pm, where the MailOutput function is used to e-mail
the output of syssumm.pl to the system where the web server is,
there is another variable called $DefaultMailCommand.  It defaults
to "/usr/bin/mailx".

The MailOutput function will use the value of $DefaultMailCommand
if $MailCommand is not defined.  If you need to use a different 
mail program (e.g., Linux) than "/usr/bin/mailx", then in your OS
module, at the very end of the InitializeOS function, change the
value of $MailCommand from "" to the path to your OS's mail 
command:

	$main::MailCommand = $MailCommand if $MailCommand;


Megabytes
---------

Always calculate megabytes by dividing by 1024 (not 1000 as
the original author had done).  For example:

	my $Size = sprintf("%.1fMB", ( $DfFields[1] / 1024 ) );

Always specify the suffix "MB" after the amount (as done in the
example above).


Return Values from Functions
----------------------------

All of the functions that are called to collect information about
the system syssumm is running on accept a single argument coming
in and return either a Scalar or an Array.

The incoming argument is the name of the Sub-category currently
being processed.  While this functionality is not currently used
in any of the OS modules, it would allow a single module to 
service two or more Sub-categories.

Some functions return a Scalar and other return an Array.
Actually, whatever the function returns in dumped into an array
called @@Response in the ProcessThisCategory function which resides
in syssumm.pl.  If there is a single element in the array, it's
merely written to the output file, otherwise the elements are
written to the output with a unique suffix ("disk-0", "disk-1",
etc.).

The following function return a scalar value:

	Category	Sub-category

	General		Vendor
			Model
			HostId

	Hardware	Memory
			StorageManager

	Network		DomainName
			DefaultRouter
			NameServer
			IPAddress
			SubnetMask

	Software	OsName
			OsVersion
			NbrOfLicenses
			Running* except for Running*FileSystems
			IpAddressResolution
			GraphicalUserInterface
			FontServer

The following functions return an Array value:

	Category	Sub-category

	Hardware	Processors
			Disks
			Tapes

	Network		NetworkInterfaces

	Software	Patches
			Printers
			ReturnLocalFileSystems
			ReturnRemoteFileSystems

Note that one easy way to determine whether a function returns
an array is my searching for a call to the function 
ForceMultipleResponses.  Typically, you'll see 2 lines right
near the end of the function:

	@@Response = ForceMultipleResponses(\@@Response);

	return @@Response;

This function is located in common.pm and makes sure that the
@@Response array has at least 2 elements in it (so that it triggers
the code in ProcessThisCategory to suffix each of the elements
in the array.  The ForceMultipleResponses and ProcessThisCategory
functions use a common tag which is not written to the output
file.

When you map your OS-specific functions into the Routines hash
in your InitializeOS function, please keep the functions in the
same order as they occur at the beginning of the syssumm.pl
program (where it maps in the dummy functions).


RunAsRoot
---------

syssumm.pl is best run by the root user.  The purpose of "RunAsRoot" 
is to allow syssumm to be run by someone other than root, but to flag 
when they get a "permission denied" message and would've gotten more 
information had they run the script as root.

The global variable $RunAsRoot is defined in syssumm.pl, it's default
value is 0 (false or off), it's set in the OS specific modules, and
returned by a function in common.pm (see below).

If you encounter a situation where a command returns "permission
denied", please set set $main::RunAsRoot to 1 (true or on).

	$main::RunAsRoot = 1;

A related comment: when you test for "permission denied", make the
test case insensitive.  I've seen different commands return 
"Permission denied" and "permission denied".

	if ( $Line =~ /permission denied/i ) {
	...

The function ReturnRunAsRoot (in common.pm) is run automatically
after all of the other categories have been processed (see syssumm.pl).
If $RunAsRoot is set, then it adds the following comment to the the 
syssumm ouput file:

	Run as root for more information

@


1.3
log
@added "Handling Different Versions of the Same Operating System" section
@
text
@d3 1
a3 1
$Header: /export/home/mohlerb/src/perl/syssumm/RCS/PROGRAMMING_STDS,v 1.2 1999/06/14 23:58:16 mohlerb Exp mohlerb $
d5 1
a5 1
$Revision: 1.2 $
d8 3
d25 1
d107 7
@


1.2
log
@Added "Return Values from Functions" section
@
text
@d3 1
a3 1
$Header: /export/home/mohlerb/src/perl/syssumm/remote/RCS/PROGRAMMING_STDS,v 1.1 1999/06/09 01:44:34 mohlerb Exp mohlerb $
d5 1
a5 1
$Revision: 1.1 $
d8 3
d68 4
a71 1
XXX
d73 4
d78 25
d216 1
a216 1
When you map your OS-specific functions into the Category hash
@


1.1
log
@Initial revision
@
text
@d3 1
a3 1
$Header$
d5 1
a5 1
$Revision$
d7 3
a9 1
$Log$
d11 1
d14 3
d18 1
d20 2
d25 21
d62 6
d93 94
@
