System

Operating system and machine configuration and control

SYNOPSIS

package require twapi
abort_system_shutdown ?-system SYSTEM?
find_domain_controller ?options?
get_active_processor_mask
get_computer_name ?NAMETYPE?
get_computer_netbios_name
get_memory_info ?options?
get_primary_domain_controller ?options?
get_primary_domain_info ?options?
get_os_description
get_os_info
get_os_version
get_processor_count
get_processor_info PROCESSOR ?options?
get_system_info ?options?
get_system_parameters_info PARAMETER
get_system_time
get_system_uptime
lock_workstation
logoff ?-force? ?-forceifhung?
min_os_version osmajor ?osminor? ?spmajor? ?spminor?
set_system_parameters_info PARAMETER VALUE ?-persist? ?-notify?
shutdown_system ?options?
suspend_system ?options?

DESCRIPTION

This module provides commands related to the system configuration including operating system functions and hardware configuration.

Overview

The commands get_os_version and min_os_version get and verify operating system version information.

The commands get_os_info and get_os_description allow retrieval of more detailed operating system information than the standard Tcl commands which do not distinguish between service packs, Professional versus Server versions and so on.

The command get_system_info returns information about the current system.

The command get_computer_name returns one of several forms of the system name. The command get_computer_netbios_name returns the NETBIOS name of the computer. Domain and workgroup information about the system can be obtained through the get_primary_domain_info command. find_domain_controller returns information about a domain controller with specified characteristics. get_primary_domain_controller returns the name of the primary domain controller of the computer.

The commands get_processor_count, get_active_processor_mask and get_processor_info retrieve information about the processors in the system including type and utilization.

The command get_memory_info returns the physical and virtual memory configuration of the system.

The command get_system_time returns the current system time in high resolution. The command get_system_uptime returns the how long the system has been running. The command shutdown_system may be used to shutdown or reboot the system. The command abort_system_shutdown may be used to abort an ongoing system shutdown. The commands logoff and lock_workstation may be used to log out of a user account and to lock a workstation respectively.

Various system settings related to the user experience can be retrieved and set through the get_system_parameters_info and set_system_parameters_info commands.

Commands

abort_system_shutdown ?-system SYSTEM?
Aborts a previously initiated system shut down or reboot. Note this is only possible if the system shutdown was initiated with a non-zero timeout value. The command enables any required privileges and restores the original privileges before returning.
find_domain_controller ?options?
Returns the name of a domain controller with specified characteristics and optionally, details about its characteristics and capabilities.
-allowstale BOOLEAN If specified as true, the system will return cached domain controller information even if it is marked as expired. Default is false. This option has no effect if -rediscover is specified as true.
-avoidself BOOLEAN If specified as true, and the command is run on a domain controller, the domain controller will return the name of another domain controller, not itself. Default is false.
-domain DOMAINNAME Specifies the domain whose domain controller is to be retrieved. If unspecified, defaults to the primary domain of the computer.
-domainguid GUID If the domain specified by the -domain option or the primary domain of system cannot be found, the command will attempt to return the domain controller for the domain with the specified GUID.
-getdetails By default, the command returns the name of the domain controller. If this option is specified, the command returns detailed information whose format is described below.
-inputnameformat NAMEFORMAT Specifies the format of the specified domain name. NAMEFORMAT may be one of dns, which implies DNS format, flat which implies flat Netbios format, or any (default) which results in the command searching both namespaces.
-justldap BOOLEAN If specified as true, the command searches for a LDAP server without caring if it is a domain controller.
-rediscover BOOLEAN If specified as true, the system ignores any cached domain controller data. Default is false. Note specifying this option as true significantly increases the time to execute the command.
-outputaddrformat ADDRFORMAT If ADDRFORMAT is specified as ip, the -dcaddr field in the returned information is the Internet address.
-outputnameformat NAMEFORMAT Specifies the format in which the domain controller and domain names should be returned. NAMEFORMAT may be one of dns, which implies DNS format, flat which implies flat Netbios format, or any (default). The command will raise an error if the name is not available in the specified format.
-prefer FEATURELIST Indicates that the domain controller that support the specified features and services is returned in preference to one that does not. FEATURELIST is a list of zero or more elements from directoryservice and timeserver (see below).
-require FEATURELIST Indicates that the domain controller to be returned must support the specified features and services. FEATURELIST is a list of zero or more features from the following: directoryservice (Active Directory support), globalcatalog (global catalog server for the forest rooted by this domain), pdc (primary domain controller for this domain) kdc (Kerberos Key Distribution center service) timeserver (running Windows Time Service) writable (must not be read-only). Note that the features pdc, kdc and globalcatalog are mutually exclusive and must not be specified together.
-site SITENAME Specifies the name of the site where the domain controller should be physically located. If an empty string (default), the command will attempt to return a controller in a site that is closest to the site of the system specified by the -system option.
-system COMPUTERNAME Specifies the DNS or NETBIOS name of the computer on which the lookup is to be done. If unspecified, defaults to the local system.
If the -getdetails option is specified, the command returns detailed information about the controller instead of just its name. The returned information is a flat list of key value pairs with the following elements:
-clientsite The name of the site containing the system specified by the -system option.
-dcname Name of the domain controller which may be either in DNS or Netbios format.
-dcnameformat Either dns if the -dcname field is in DNS format, or netbios if it is a Netbios name.
-dcaddr Address of the domain controller. This may be either the Netbios address or the IP address depending on the value of the specified -outputaddrformat option.
-dcaddrformat Either ip if the -dcaddr field is in IP address format, or netbios if it is a Netbios address.
-dcsite The name of the site containing the domain controller.
-dnsforest Name of the domain that is at the root of the directory service tree.
-dnsforestformat Either dns if the -dnsforestformat field is in DNS format, or netbios if it is a Netbios name.
-domainguid GUID of the domain.
-domain Name of the domain.
-domainformat Either dns if the -domain field is in DNS format, or netbios if it is a Netbios name.
-features Contains a list describing domain controller features. This list may contain zero or more of the following: directoryservice (Active Directory support), globalcatalog (global catalog server for the forest rooted by this domain), pdc (primary domain controller for this domain), kdc (Kerberos Key Distribution center service), timeserver (running Windows Time Service), goodtimeserver (running Windows Time Service with a physical clock), writable (is not read-only).
Note that any of these fields may have empty string values if the information is not relevant or cannot be found.
get_active_processor_mask
Returns a mask representing the processors configured into the system.
get_computer_name ?NAMETYPE?
Returns the name of the computer. NAMETYPE must be one of the following:
netbios Returns the NETBIOS name of the local computer or the cluster virtual server if it is in a cluster.
dnshostname Returns the DNS host name of the local computer or the cluster virtual server if it is in a cluster.
dnsdomain Returns the DNS domain of the local computer or the cluster virtual server if it is in a cluster.
dnsfullyqualified Returns the fully qualified DNS domain of the local computer or the cluster virtual server if it is in a cluster.
physicalnetbios Returns the NETBIOS name of the local computer.
physicaldnshostname Returns the DNS host name of the local computer.
physicaldnsdomain Returns the DNS domain of the local computer.
physicaldnsfullyqualified Returns the fully qualified DNS name of the local computer.
If NAMETYPE is not specified, it defaults to netbios.
get_computer_netbios_name
Returns the NETBIOS name of the computer.

Example: print the computer name
get_memory_info ?options?
Returns various information about the physical and virtual memory configuration of the system. The information returned is in the form of a flat list of the form "field1 value1 field2 value2 ..." depending on which of the following options are specified:
-all Returns all the options listed below.
-allocationgranularity Returns the granularity with which virtual memory is allocated.
-availcommit Returns the amount of free virtual memory available to commit.
-availphysical Returns the amount of free physical memory.
-maxappaddr Returns the highest address that may be mapped into an application's address space.
-minappaddr Returns the lowest address that may be mapped into an application's address space.
-pagesize Returns the size of a virtual memory page
-swapfiles Returns a list of the swap files for the system.
-swapfiledetail Returns a flat list of pairs corresponding to the swap files. The first element of each pair is the name of the swap file. The second element is a list of consisting of the current size of the file (in pages), the number of pages in use, and the peak number of pages that have been used in the file.
-totalcommit Returns the maximum amount of virtual memory that can be committed without extending the swap files.
-totalphysical Returns the total amount of physical memory installed in the system.
Example: Show virtual memory statistics

get_primary_domain_controller ?options?
Returns the primary domain controller (PDC) for a domain. The command find_domain_controller should be preferred to this command.

The following options may be specified:
-domain DOMAINNAME Specifies the domain whose PDC is to be retrieved. If unspecified, defaults to the primary domain.
-system COMPUTERNAME Specifies the DNS or NETBIOS name of the computer on which the lookup is to be done. If unspecified, defaults to the local system.
get_primary_domain_info ?options?
Returns information about the primary domain or workgroup of the system as a flat list of option value pairs. The following options control what information is returned.
-all Equivalent to specifying all options.
-dnsdomainname Returns the DNS name of the primary domain.
-dnsforestname Returns the DNS forest name of the primary domain.
-domainguid Returns the GUID of the primary domain.
-name Returns the domain or workgroup name.
-sid Returns the SID of the primary domain.
-type Returns workgroup or domain depending on whether the system belongs to a workgroup or a domain.
If the system belongs to a workgroup, all options will return empty values except -name and -type.
get_os_description
This commmand returns the same operating system information as returned by get_os_info but in a form suitable for displaying to a user.
get_os_info
This command retrieves operating system version and configuration information and returns a keyed list with the following fields:
platform String identifying the operating system base platform. Currently this is always NT.
os_major_version Major operating system version.
os_minor_version Minor operating system version.
sp_major_version Major service pack version.
sp_minor_version Minor service pack version.
os_build_number Contains the operating system build number.
system_type Indicates the operating system base type. This is workstation for Windows NT 4.0 Workstation, Windows 2000 Professional, or any Windows XP operating system versions. If the system is a domain controller, this value is domain_controller. In all other cases, this value is server.
suites Contains a list of values (see below) that indicate various options that may be installed as part of the operating system.
The suites element in the returned array contains a list of values from the following set that indicates additional operating system components that are present:
backoffice Microsoft BackOffice components are installed
blade Windows .NET Server 2003 family Web Edition is installed
terminal Terminal Services are installed
datacenter Windows 2000 Datacenter Server or Windows .NET Server 2003 family Datacenter Edition is installed
enterprise Windows NT 4.0 Enterprise Edition, Windows 2000 Advanced Server, or Windows .NET Server 2003 family Enterprise Edition is installed
smallbusiness Microsoft Small Business Server is installed
smallbusiness_restricted Microsoft Small Business Server is installed with the restrictive client license in force
personal Windows XP Home Edition is installed
pagesize Contains the number of bytes in a page
min_app_addr Contains the lowest possible address in the application's virtual memory space.
max_app_addr Contains the highest possible address in the application's virtual memory space.
allocation_granularity Contains the granularity of virtual memory allocation.
Example: check if terminal services are present

get_os_version
This command returns the operating system version as list of four elements - the operating system major version number, the operating system minor version number, the service pack major version number, the service pack minor version number.

Example: verify if a service pack is installed
get_processor_count
Returns the number of processors in the system.
get_processor_info PROCESSOR ?options?
Returns various pieces of information related to the processors in the system. PROCESSOR identifies the processor whose information is to be retrieving. If specified as an empty string, information across all processors in the system is returned. The information returned is in the form of a flat list of the form "field1 value1 field2 value2 ...". The fields returned depend on the specified options and their values may be scalars (e.g. -name) or rate based measured over an interval (e.g. -processorutilization). The option -interval may be used to indicate the interval over which the rate based fields are measured. One of more of the following options may be specified with the command:
-all Returns all fields listed below.
-apcbypassrate Returns the field apcbypassrate which is the rate (per second) that kernel APC interrupts were bypassed as computed over the measured interval.
-arch Returns the processor architecture.
-dpcbypassrate Returns the field dpcbypassrate which is the rate (per second) that deferred procedure calls were avoided as computed over the measured interval.
-dpcqueuerate Returns the field dpcqueuerate containing the rate at which deferred procedure calls are being added to the DPC queue as measured over the specified interval.
-dpcrate Returns the field dpcrate containing the rate at which deferred procedure calls are being added to the DPC queue. This rate is based on the observed value over the last two timer ticks of the processor clock, and not that over the measured interval.
-dpctime The amount of CPU time in 100ns units spent in servicing deferred procedure calls. Note this value is included in the -privilegedtime value.
-dpcutilization Returns the field dpcutilization containing the percentage of time that this processor has spent servicing deferred procedure calls over the measured interval. This is included in the privilegedutilization value.
-idletime The amount of idle CPU time in 100ns units since system start. Note this value is included in the -privilegedtime value.
-interrupts Returns the total number of interrupts serviced since system start.
-interruptrate Returns the field interruptrate containing the number of hardware interrupts being processed per second over the measured interval.
-interrupttime The amount of CPU time in 100ns units spent in servicing interrupts. Note this value is included in the -privilegedtime value.
-interruptutilization Returns the field interruptutilization containing the percentage of time that this processor has spent servicing interrupts over the measured interval. This is included in the privilegedutilization value.
-privilegedtime The amount of privileged (kernel) context CPU time since system start in 100ns units. Note this includes the DPC, interrupt and idle CPU cycles.
-privilegedutilization Returns the field privilegedutilization containing the percentage of time that this processor has spent executing a non-idle thread in privileged mode during the measured interval.
-processormodel Returns the processor model. PROCESSOR must not be an empty string if this option is specified.
-processorname Returns a human readable form of the processor description. PROCESSOR must not be an empty string if this option is specified.
-processorrev Returns the processor revision as defined by the CPU manufacturer. PROCESSOR must not be an empty string if this option is specified.
-processorspeed Returns the nominal speed in Mhz of the processor PROCESSOR must not be an empty string if this option is specified.
-processorutilization Returns the field processorutilization containing the percentage of CPU time that this processor has been executing a non-idle thread over the measured interval.
-processorlevel Returns the processor level as defined by the CPU manufacturer.
-usertime The amount of user context CPU time in 100ns units since the system was started.
-userutilization Returns the field userutilization containing the percentage of time that this processor has spent executing a non-idle thread in user mode during the measured interval.
get_system_info ?options?
Returns various pieces of information related to the system. The information returned is in the form of a flat list of the form "field1 value1 field2 value2 ...". One of more of the following options may be specified with the command to control what information is returned:
-all Returns all fields listed below.
-eventcount Returns the number of synchronization events in use.
-handlecount Returns the number of handles that are currently open.
-mutexcount Returns the number of synchronization mutexes in use.
-processcount Returns the number of processes that are currently running.
-sectioncount Returns the number of sections in use.
-semaphorecount Returns the number of synchronization semaphores in use.
-sid Returns the SID of the system.
-threadcount Returns the number of threads that are currently running.
-uptime Returns the number of seconds elapsed since the system was booted.
get_system_parameters_info PARAMETER
This command wraps the Windows SystemParametersInfo function and allows retrieval of various user interface settings such as screensaver timeout, mouse speed etc. The information retrieved depends on the PARAMETER which must be one of the SPI_ symbols listed in the SystemParametersInfo documentation.
get_system_time
Returns the current system time in UTC as the number of 100 nanosecond units since Jan 1, 1601. This can be converted to a format suitable for use with the clock command through the use of the command large_system_time_to_secs_since_1970.
get_system_uptime
Returns the number of seconds elapsed since the system was booted.
lock_workstation
Initiates a request to lock the work station display.
logoff ?-force? ?-forceifhung?
Logs off the current session. If -force is specified, it forces processes to terminate without notifying them. This options should generally not be specified as it can result in data loss. If -forceifhung is specified, it only terminates processes if they do not respond to the session end notifications.
min_os_version osmajor ?osminor? ?spmajor? ?spminor?
This function checks that the operating system version meets the specified minimum version. It returns 1 if the operating system version is greater than osmajor.osminor.spmajor.spminor. Otherwise it returns 0. Any unspecified optional arguments default to 0.
set_system_parameters_info PARAMETER VALUE ?-persist? ?-notify?
This command wraps the Windows SystemParametersInfo function and allows setting of various user interface settings such as screensaver timeout, mouse speed etc. The information retrieved depends on the PARAMETER which must be one of the SPI_ symbols listed in the SystemParametersInfo documentation. The corresponding setting is assigned VALUE.

If the -persist is specified, the changed setting is written to the user's profile. If -notify is specified, all applications are notified of the change. Note -notify only has effect if -persist is also specified since other applications will update based on the user's persistent profile.
shutdown_system ?options?
Initiates a system shut down or reboot. The command enables any required privileges and restores the original privileges before returning.

The following options may be specified:
-system SYSTEMNAME Specifies the system to be shut down. By default, this is the local system.
-timeout SECONDS Specifies the amount of time to wait before shutting down the system. During this time, a shutdown dialog is displayed to the user. If a value of 0 is specified, the system is shut down immediately and no dialog is displayed to the user.
-message MESSAGE Specifies a message to be displayed to the user in the shutdown dialog.
-force Normally, the system displays a dialog box asking the user to close any applications with unsaved data. If the -force option is specified, applications are forcible closed resulting in possible data loss.
-restart If specified, the system is restarted after the shut down.
suspend_system ?options?
Places the system in a stand by or hibernate state. The command takes the following options:
-state STATE STATE must be one of standby (default) or hibernate depending on whether the state into which the system is to be placed.
-force BOOLEAN If false (default), the system sends a PBT_ATMQUERYSUSPEND message to all applications before placing the system in stand by or hibernate states. If this option is specified as true, the message is not sent and the system is immediately placed into the appropriate state.
-disablewakeevents BOOLEAN If false (default), system wake events remain enabled. If true they are disabled.

COPYRIGHT

Copyright © 2003-2009 Ashok P. Nadkarni

Tcl Windows API 2.2.3 Privacy policy