.\" 
.TH mcsysinfoperl 3 "12 April 2003"
.ds ]W www.MagniComp.com
.SH NAME
mcsysinfoperl \- MagniComp(tm) SysInfo(tm) Perl API to obtain detailed system information in a platform neutral manner
.SH SYNOPSIS
use lib ('/opt/sysinfo/lib/mcSysInfo');
.br
use mcSysInfo;
.br
.sp
$mcSysInfo = mcSysInfo->New;
.br
.sp
# Optional: Specify pathname to sysinfo(1)
.br
$mcSysInfo->Program($SysInfoPath);
.br
# Optional: Use $InFile in place of sysinfo(1)
.br
$mcSysInfo->InputFile($InFile);
.br
# Optional: Limit data to class List
.br
$mcSysInfo->Class(@List);
.sp
.br
# Retrieve data and populate $mcSysInfo
.br
$mcSysInfo->Retrieve(%Options);
.br
.sp
.nf
# Raw report interface
$mcSysInfo->ReportSet($Options);
for ( ; ; ) {
    my $Line = $SysInfo->ReportLine;
    if (!defined($Line)) {
        last;
    }
    printf "%s\\n", $Line;
}
$mcSysInfo->ReportEnd;
.SH DESCRIPTION
The
.B mcSysInfo
.B perl(1)
interface is part of
.B SysInfo(tm)
from
.B MagniComp(tm)
(see \fBmcsysinfo(1)\fR for an overview).
is called it obtains the requested data from a source determined
as follows:
.RS
.IP mcSysInfo->InputFile
If this member is set, the data is read from this file.
The file should be in 
.B mcsysinforeport(5) format.
.IP "Remote host via SSP"
If
.B mcSysInfo->Host
is set, then data is retrieved via the SSP protocol from the
specified host.
.IP "Local File Cache"
If a local file cache of the requested data is available, the
data is read from the cache.
.IP "Local via SIE"
The 
.B "SysInfo Engine(tm)"
(SIE)
is run locally to obtain data.
As the data is read from SIE it is saved to a local file cache
(see 
.B "FILE CACHE"
for more details).
.RE
In all cases,
the data is parsed into 
.I perl(1)
objects and made available as members of
.I mcSysInfo
(see below for details).
.PP
If you wish to retrieve raw "report" format data one line at
a time,
first call
.B mcSysInfo->ReportSet
and then call
.B mcSysInfo->ReportLine
to retrieve one line of "report" format data.
This function returns undef when all data has been read.
The
.B mcSysInfo->ReportEnd
function will close any open file descriptors.
.SH "FILE CACHE"
When data is retrieved via
.B mcSysInfo->Retrieve
it is cached in files under the
\fB/tmp/mcsysinfo.cache.\fIUID\fR
(where \fIUID\fR is the UID of the user calling the API) directory.
An alternate directory can be specified by passing the hash
value of 
\fBCacheDir=>\fIDir\fR
.SH "OBJECT DEFINETIONS"
.SS "OBJECT mcSysInfo"
.PP
The following is a list of object members available for the
.I mcSysInfo
object:
.RS
.IP "\fBClass(\fI@List\fB)\fR"
Limit the class of information retrieved and returned to 
.I @List.
The contents of
.I @List
should be valid class names as returned by
.B "sysinfo -list class"
The default is to return all class types.
.IP "\fBDestroy\fR"
This function should be called when the object is no longer
needed.
It will gracefully destroy the object including shutting down any
remote connections which were established.
.IP "\fBHost(\fIName\fB)\fR"
Retrieve all information from server host
.I Name
which can either be a hostname or IP address.
The host must be running
.B mcsysinfod(1).
.IP "\fBInputFile(\fIPath\fB)\fR"
Use the file specified by
.I Path
as input instead of running the
.B sysinfo(1)
program.
The file must be the output from
.B "sysinfo -repsep '|' -format report"
The default is to run the
.B sysinfo(1)
program.
.IP "\fBPassword(\fIString\fB)\fR"
Use
.I String
as the plain text password
to authenticate as (when required)
when connecting to a
.B mcsysinfod(1)
server.
You must set
.B Password
in conjunction with
.B Username.
.IP "\fBPort(\fINumber\fB)\fR"
Connect to
.B mcsysinfod(1)
.IP "\fBProgramArgs(\fI@Array\fB)\fR"
Specify 
.B @Array
as a list of options to be passed to
.B Program.
.IP "\fBRetrieve(\fI%Options\fB)\fR"
This member retrieves the requested data as documented in 
.B DESCRIPTION.
It accepts a hash argument of options and understands
the following:
.RS
.IP \fBCache=>\fB1|0\fR
If
.B Cache
is set to
.B 1
or no
.B Cache
value is specified (the default), caching will be enabled.
If
.B Cache
is set to
.B 0
caching will be disabled.
.IP \fBCacheDir=>\fIDir\fR
Cache directory.
.IP \fBExpireTime=>\fISeconds\fR
Number of seconds before cached data expires.
.IP \fBRefresh=>\fB1\fR
Refresh all requested data in the cache.
Data is retreived directly from authorative sources and the cache
files are updated.
.RE
.IP "\fBUsername(\fIName\fB)\fR"
Use
.I Name
as the username to authenticate as (when required)
when connecting to a
.B mcsysinfod(1)
server.
You must set
.B Username
in conjunction with
.B Password.
.IP "\fBVersion\fR"
Returns a hash of version information.
The following hash members may be returned:
.RS
.IP "\fBPRODUCT\fR"
The overall product version.
.IP "\fBSIE\fR"
The version of the SysInfo Engine (SIE).
on
.B Host.
.RE

.RE
.PP
The following 
.I mcSysInfo
object members contain the system configuration data after
.B mcSysInfo->Retrieve
is called:
.RS
.IP "\fBGeneral\fR"
General system configuration data.  See
.B "OBJECT mcGeneral"
below.
.IP "\fBHardware\fR"
Hardware (device) configuration data.  See
.B "OBJECT mcHardware"
below.
.IP "\fBMagniCompLic\fR"
MagniComp License information.  See
.B "OBJECT mcMagniCompLic"
below.
.IP "\fBNetIf\fR"
Network Interface information.
See
.B "OBJECT mcNetIf"
below.
.IP "\fBNetwork\fR"
Network configuration information.
See
.B "OBJECT mcNetwork"
below.
.IP "\fBLicense\fR"
License information.
See
.B "OBJECT mcLicense"
below.
.IP "\fBSoftware\fR"
Installed software data.  See
.B "OBJECT mcSoftware"
below.
.IP "\fBPartition\fR"
Disk partition data.  See
.B "OBJECT mcPartition"
below.
.IP "\fBPrinter\fR"
Printer queue data.  See
.B "OBJECT mcPrinter"
below.
.IP "\fBSysConf\fR"
.RS
.IP "\fBEntries\fR"
Returns a hash of 
.B mcDevInfo
objects each of which details an installed device.
The hash key is a unique device name.
The value is an
.B mcDevInfo
object.
See
.B "OBJECT mcDevInfo"
for details.
.RE
.PP
A special device entry with a key of
.B "TOTAL DISK"
contains the total amount of disk space on the system.
.SS "OBJECT mcDevInfo"
The table below specifies the valid members of the
.B mcDevInfo
object and describes their usage.
See
.B mcsysinfo(3)
for more details describing each member.
.br
.sp
.RS
.TS
l l l
l l l.
\fBMember	Description	Returns\fR
Aliases	Aliases	Array
AltName	AKA Name	Scalar
Bus	Bus no. of device	Scalar
Capacity	Capacity (size) of device	Scalar
ClassType	Class Type	Scalar
DescList	List of misc descriptions	Array
DevNum	Device no. on Bus	Scalar
DevSpec	Device type specific data	varies
Driver	Driver name	Scalar
Files	Files	Array
Ident	Identifier	Scalar
Model	Model	Scalar
ModelDesc	Model Description	Scalar
Name	Name of device	Scalar
Next	Next peer device	Scalar
NodeID	Node ID	Scalar
Part	Part #	Scalar
Port	Port no. on Bus	Scalar
Revision	Revision	Scalar
Serial	Serial #	Scalar
Slaves	List of child devices	Array
when 
.B mcDevInfo->Type
is 
.B CPU.
See
.B mcsysinfo(3)
for more details describing each member.
.br
.sp
.RS
.TS
l l l
l l l.
\fBMember	Description	Returns\fR
Arch	Architecture	Scalar
ArchVer	Architecture Version	Scalar
BitSize	Bit Size	Scalar
Caches	List of onboard caches	Array
HasFPU	Has FPU	Scalar
Man	Manufacturer	Scalar
Model	Model	Scalar
Serial	Serial #	Scalar
Speed	Clock Speed	Scalar
Stepping	Stepping	Scalar
.TE
.RE

.SS "OBJECT mcCacheInfo"
The table below specifies the valid members of the
.B mcCacheInfo
object and describes their usage.
A
.B mcCacheInfo
object is usually available via the
.B mcDevInfo->DevSpec->Caches
array when 
.B mcDevInfo->Type
is 
.B processor.
See
.B mcsysinfo(3)
for more details describing each member.
.br
.sp
.RS
.TS
l l l
l l l.
\fBMember	Description	Returns\fR
Name	Name of the cache	Scalar
Device	Name of device cache is on	Scalar
Enabled	Is the cache enabled?	Scalar
.RE

.SS "OBJECT mcGeneral"
The
.B mcGeneral
object contains general system configuration data.
The table below specifies the valid members of the
.B mcGeneral
object and describes their usage.
See
.B mcsysinfo(3)
for more details describing each member.
.br
.sp
.RS
.TS
l l l
l l l.
\fBMember	Description	Returns\fR
Hostname	Host Name	Scalar
HostAliases	Host Aliases	Array
HostAddrs	Host Addresses	Array
HostId	Host ID	Scalar
Serial	Serial #	Scalar
ManShort	Manufacturer (Short)	Scalar
ManLong	Manufacturer (Long)	Scalar
Man	Manufacturer	Scalar
Model	Model	Scalar
PhysMem	Physical Memory	Scalar
VirtMem	Virtual Memory	Scalar
RomVer	ROM Version	Scalar
NumCpu	Number of CPU (Physical)	Scalar
NumCpuVirt	Number of CPU (Virtual)	Scalar
CpuType	CPU Type	Scalar
CpuSpeed	CPU Speed	Scalar
AppArch	App Architecture	Scalar
KernArch	Kernel Architecture	Scalar
KernBits	Kernel Bit Size	Scalar
OSname	OS Name	Scalar
OSver	OS Version	Scalar
OSdist	OS Distribution	Scalar
OSdistName	OS Distribution Name	Scalar
OSdistShName	OS Distribution Short Name	Scalar
OSdistVer	OS Distribution Version	Scalar
KernVer	Kernel Version	Scalar
BootTime	Boot Time	Scalar
CurrentTime	Current Time	Scalar
LibcName	Libc Name	Scalar
LibcVer	Libc Version	Scalar
.TE
.RE

The members of this object are:
.br
.sp
.RS
.TS
l l l
l l l.
\fBMember	Description	Returns\fR
SoftName	Software Name	Scalar
SoftVer	Software Version	Scalar
Type	Type of license	Scalar
TypeDesc	Description of Type of license	Scalar
Port	Port license server listens on	Scalar
File	File containing license	Scalar
ServerSoft	Name of license server software	Scalar
ServerVer	Version of license server software	Scalar
VendorServerSoft	Name of license vendor's server software	Scalar
VendorServerVer	Version of license vendor's server software	Scalar
Count	# of licenses (RTUs)	Scalar
Issuer	Who issued license	Scalar
Hostid	Hostid license is tied to	Scalar
IssueDate	Date license was issued	Scalar
StartDate	Date license starts	Scalar
ExpireDate	Date license expires	Scalar
DaysLeft	# days before expiration	Scalar
Key	License key	Scalar
Serial	Serial # of license	Scalar
MinCPU	Minimum # of CPUs license is valid for	Scalar
MaxCPU	Max # of CPUs license is valid for	Scalar
AccountName	Name of customer's account	Scalar
AccountNumber	Customer account number	Scalar
Comment	Free form comment field	Scalar
LicenseURL	URL of license terms	Scalar
HomePageURL	URL of product	Scalar
Status	Status of license	Scalar
HostName	Name of host license is tied to	Scalar
.TE
.RE

.SS "OBJECT mcMagniCompLic"
The
.B mcMagniCompLic
object contains data on MagniComp SysInfo licenses.
The following are valid members:
.RS
.IP "\fBEntries\fR"
A hash table of SysInfo licenses each contained in a
.B mcLicenseInfo
object.
.IP "\fREntriesReport\fR"
A hash table of SysInfo licenses in
.B mcsysinforeport(5)
The value is an
.B mcName
object.
See
.B "OBJECT mcName"
for details.
.RE

.SS "OBJECT mcNetIf"
This object contains information about all network interfaces
found on the scanned system.
The following are the valid members for this object:
.RS
.IP "\fBEntries\fR"
A hash table of
.B mcNetIfInfo
objects, each of which contains the actual network interface data.
.RE

.SS "OBJECT mcNetIfInfo"
The table below specifies the valid members of the
.B mcNetIfInfo
object and describes their usage.
A
.B mcNetIfInfo
object is usually available via
.B mcDevInfo->DevSpec
when 
.B mcDevInfo->Type
is 
.B netif
as well as in the
.B Entries
hash in the
.B mcNetIf
object.
See
.B mcsysinfoc(3)
for more details describing each member.
.br
.sp
.RS
.TS
l l l
l l l.
\fBMember	Description	Returns\fR
Name	NIC Name	Scalar
Type	NIC Address Type	Scalar
IfType	NIC Interface Type	Scalar
HostAddr	NIC Host Address	Scalar
HostName	NIC Host Name	Scalar
MACaddr	NIC MAC Current Address	Scalar
.RE

.SS "OBJECT mcNetwork"
This object contains information about network configuration.
The following are the valid members for this object:
.RS
.IP "\fBEntries\fR"
A hash table of
.B mcNetIfInfo
objects, each of which contains the actual network interface data.
There is currently only one supported keyword called
.B Network.
.RE

.SS "OBJECT mcNetworkInfo"
The table below specifies the valid members of the
.B mcNetworkInfo
object and describes their usage.
A
.B mcNetworkInfo
object is usually available via
the
.B Entries
hash in the
.B mcNetwork
object.
See
.B mcsysinfoc(3)
for more details describing each member.
.br
.sp
.RS
.TS
l l l
l l l.
\fBMember	Description	Returns\fR
DefGatewayIP	Default gateway IP address	Scalar
DefGatewayName	Default gateway hostname	Scalar
DnsDomain	DNS domain name	Scalar
DnsServerIPs	DNS server IP addresses	Array
DnsServerNames	DNS server hostnames	Array
NisDomain	NIS domain name	Scalar
NisServerMethod	NIS server selection method	Scalar
NisServerIPs	NIS server IP addresses	Array
NisServerNames	NIS server hostnames	Array
NisServerCurrent	Currently bound NIS server	Scalar
NisMaster	NIS master server	Scalar
.TE
.RE

.SS "OBJECT mcPartition"
The
for details.
.RE
.SS "OBJECT mcPartInfo"
The table below specifies the valid members of the
.B mcPartInfo
object and describes their usage.
See
.B mcsysinfo(3)
for more details describing each member.
.br
.sp
.RS
.TS
l l l
l l l.
\fBMember	Description	Returns\fR
Name	Partition Name	Scalar
DevName	Device Name	Scalar
DevPath	Device Path	Scalar
DevPathRaw	Device Path Raw	Scalar
BaseName	Base Name	Scalar
Slice	Slice	Scalar
Num	Partition #	Scalar
Type	Type	Scalar
TypeDesc	Type Description	Scalar
TypeNum	Type Number	Scalar
UsageStatus	Usage Status	Scalar
MntName	Mount Name	Scalar
MntOpts	Mount Options	Array
Size	Size (MB)	Scalar
AmtUsed	Amount Used (MB)	Scalar
SecSize	Sector Size (bytes)	Scalar
StartSect	Starting Sector	Scalar
EndSect	Ending Sector	Scalar
NumSect	Number of Sectors	Scalar
.TE
.RE
.SS "OBJECT mcPrinter"
The
.B mcPrinter
object contains data on what printer queues are on the system.
The following are valid members:
.RS
.IP "\fBEntries\fR"
Returns a hash of 
.B mcPrinterInfo
objects each of which details a printer queue.
The hash key is a unique printer name.
The value is an
.B mcPrinterInfo
object.
See
l l l
l l l.
\fBMember	Description	Returns\fR
Name	Queue Name	Scalar
Aliases	Queue Aliases	Array
Descript	Description of queue	Scalar
Vendor	Printer Vendor	Scalar
Model	Printer Model	Scalar
Proto	Communication Protocol	Scalar
Device	Pathname to printer device	Scalar
Server	Name of server printer is on	Scalar
RemoteQueue	Queue name on Server	Scalar
Langs	Supported printer languages	Array
SpoolDir	Spool Directory	Scalar
MaxJobSize	Max size of each job	Scalar
DescList	Misc descriptions	Array
.TE
.RE

.SS "OBJECT mcSoftware"
The
.B mcSoftware
object contains data on what software is installed on the system.
The following are valid members:
.RS
.IP "\fBEntries\fR"
Returns a hash of 
.B mcSoftInfo
objects each of which details an installed software package.
The hash key is a unique package name.
The value is an
.B mcSoftInfo
object.
See
.B "OBJECT mcSoftInfo"
for details.
.RE
.SS "OBJECT mcSoftInfo"
The table below specifies the valid members of the
.B mcSoftInfo
object and describes their usage.
See
.B mcsysinfo(3)
for more details describing each member.
.br
.sp
.RS
.TS
l l l
l l l.
\fBMember	Description	Returns\fR
Name	Name of package	Scalar
InstDate	Installation Date	Scalar
BuildDate	Build Date	Scalar
ProdStamp	Production Stamp	Scalar
BaseDir	Base Directory	Scalar
PkgDeps	List of dependant packages	Array
DiskUsage	Disk Usage	Scalar
FileList	File List	Array
VendorName	Vendor Name	Scalar
VendorEmail	Vendor Email	Scalar
VendorPhone	Vendor Phone #	Scalar
VendorStock	Vendor Stock #	Scalar
DescList	List of misc description data	Array
Master	Name of master package	Scalar
MasterVer	Version of master	Scalar
MasterRev	Revisionof master	Scalar
Slaves	List of child packages	Array
Next	Next peer package	Scalar
.TE
.RE

.SS "OBJECT mcSysConf"
The
.B mcSysConf
object contains data on system configuration data obtained via
.B sysconf(3).
The following are valid members:
.RS
.IP "\fBEntries\fR"
Returns a hash of 
.B mcName
objects each of which details a SysConf entry.
The hash key is a unique SysConf variable name.
The value is an
.B mcName
object.
See
.B "OBJECT mcName"
for details.
.RE
.SS "OBJECT mcName"
The table below specifies the valid members of the
.B mcName
object and describes their usage.
See
.B mcsysinfo(3)
for more details describing each member.
.br
.sp
.RS
.TS
l l l
l l l.
.B mcSysInfo
interface.
.PP
The following example displays the hostname and system model:
.nf
.RS
.sp
use lib ('/opt/sysinfo/lib/mcSysInfo');
use mcSysInfo;

$si = mcSysInfo->New;
# Only retrieve the info we need
$si->Class('General');
$si->Retrieve();

printf ("System hostname is %s\\n", $si->General->Hostname);
printf ("System model is %s\\n", $si->General->Model);
.RE
.fi
.PP
The following example displays a list of all device names and
their model (if known):
.RS
.nf
.sp
use lib ('/opt/sysinfo/lib/mcSysInfo');

use mcSysInfo;

$si = mcSysInfo->New;
# Only retrieve the info we need
$si->Class('Hardware');
$si->Retrieve();

foreach my $Key (keys %{ $si->Hardware->Entries }) {
	my $di = $si->Hardware->Entries->{$Key};
	printf ("Device %s is a %s\\n", $Key, $di->Model);
}

.fi
.RE
.SH FILES
/opt/sysinfo/bin/mcsysinfo 	\- Path to sysinfo program
.SH "SEE ALSO"
mcsysinfo(1),
perl(1),
mcsysinfoc(3)
.SH URL
http://www.MagniComp.com/sysinfo