Tcl Windows API extension

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.

System

SYNOPSIS

DESCRIPTION

Overview

Commands

COPYRIGHT

TWAPI 2.1.6 Documentation