Documentation of the module nt

by Peter Verhas

Table of Contents

[Contents]

1. Introduction

[Contents]

2. The module NT

=abstract Windows NT specific functions =end

This module implements some Win32 system calls that are not implemented in the core of ScriptBasic but can be helpful for those who want to write system maintenance scripts using ScriptBasic.

The reason that these functions are not implemented inside ScriptBasic is that ScriptBasic itself is portable, and whenever a programmer writes a program in pure ScriptBasic it should execute the same way under UNIX as well as under Windows NT/Win98/W2K.

Programs using the module nt however are Win32 specific and will not run unaltered under UNIX.

[Contents]

3. Handling the registry

These functions handle the registry. The argument that specifies a registry element should start with the name of the top level registry hives. These are:

The registry names in the documentation usually refer to the ScriptBasic configuration file location regis-try element. This is only an example, but you should not alter is from a program without good reason. Generally saying: be reasonable and think twice before altering the registry from a program.

[Contents]

4. Read the registry

a = nt::RegRead("HKLM\\Software\\ScriptBasic\\config")

This function reads a registry entry and returns the value of the entry or undef if the entry does not ex-ists or if it is not readable by the interpreter process/thread.

If the argument string specifies a key and the last character of the argument is \ then the default value for the key is retrieved. Note that HKLM\Software\ScriptBasic can have a subkey named config as well as a value named config. The string "HKLM\\Software\\ScriptBasic\\config" refers to the value while "HKLM\\Software\\ScriptBasic\\config\\" refers to the default value of the subkey.

[Contents]

5. Delete a registry value or key

nt::RegDel "HKLM\\Software\\ScriptBasic\\config"

This function deletes a value from the registry or deletes a key from the registry. If the argument specifies a registry key it should not have any subkeys. If the registry value or key cannot be deleted for some reason the function raises error that the programmer should capture using the ON ERROR GOTO statement.

[Contents]

6. Write a registry value

nt::RegWrite "HKLM\\Software\\ScriptBasic\\config",value

This function writes the value of a registry value. The key should already exist. If the key is non-existent or the value is not alterable by the program the function raises error that the programmer should capture using the ON ERROR GOTO statement.

[Contents]

7. Display a message box

i = nt::MsgBox("Text","Caption" [,"buttons","style",defbutton])

This function displays a Windows message box on the screen and waits for the user to press one of the buttons of the message box. The function should get two mandatory and three optional arguments.

The arguments:

The return value of the function is a one character string containing one of the characters A, C, I, N, O, R, Y for the pressed buttons respectively: Abort, Cancel, Ignore, No, OK, Retry, Yes.

The parameters "buttons" and "style" are not case sensitive. The return value is uppercase character.

The following example tests all the possible message boxes:

import nt.bas

nt::MsgBox """This program test the various text boxes.

In the coming message boxes press the various keys as requested by the text and check on the console window that the program reported the correct button you pressed. (Only initials are printed.) ""","Initial MsgBox"

splita " |ARI|O|RC|YN|YNC" BY "|" TO buttons splita " |W|I|Q|S" BY "|" TO marks

for j=lbound(marks) to ubound(marks)

for i=lbound(buttons) to ubound(buttons)

for d=1 to len(buttons[i]) print i," ",buttons[i]," ",j," ",marks[j]," ",d,"\n" R = nt::MsgBox(buttons[i],marks[j],buttons[i],marks[j],d) print R print

next d next i next j

[Contents]

8. ShutDown a Windows NT server or workstation

Calling this function shuts down a Windows NT Server, Workstation or W2K machine. It was tested on a W2K Professional.

nt::ShutDown "machine","message",timeout,force,reboot

The first argument is the name of the machine to reboot. If this is undef then the actual machine running is shutting down.

The second argument is the message that the system will display on the screen before starting the actual shutdown. This argument may also be undef in case there is no need for such a message.

The argument timeout is the number of seconds that the operating system will wait before starting the actual shutdown.

force specifies whether applications with unsaved changes are to be forcibly closed. If this parameter is TRUE, such applications are closed. If this parameter is FALSE, a dialog box is displayed prompting the user to close the applications.

reboot specifies whether the computer is to restart immediately after shutting down. If this parameter is TRUE, the computer is to restart. If this parameter is FALSE, the system flushes all caches to disk, clears the screen, and displays a message indicating that it is safe to power down or switches off automatically.

The function calls the Windows NT InitiateSystemShutdown function. Some sentences of this ScriptBasic documentation was copied from the original documentation of the Windows NT system API documentation.

[Contents]

9. Get the list of the running processes

This procedure gathers the information on the actually executiong processes and returns the information in an array.

nt::ListProcesses PS

The result is stored in the variable PS. This will be an array, with each element being also an array holding information for the process. The number of running processes can be determined using ubound(PS)+1.

The elements of the array is indexed from 0 to 8 contaiing the following elements:

[Contents]

10. Start a Windows NT service

This function starts an installed Windows NT service.

nt::StartService "Service name"

The argument for this subroutine call is the name of the service to start. This is the name that was used to create the service and you can read this name when you start the graphical service control manager application.

The subroutine returns undef value. If the service can not be started the function raises error. Calling this subroutine for an already running service is not an error.

[Contents]

11. Stop a Windows NT service

This function stops an already running Windows NT service.

nt::StopService "Service name"

The argument for this subroutine call is the name of the service to start. This is the name that was used to create the service and you can read this name when you start the graphical service control manager application.

The subroutine returns undef value. If the service can not be stopped the function raises error.

[Contents]

12. Pause a Windows NT service

This function pauses an already running Windows NT service.

nt::PauseService "Service name"

The argument for this subroutine call is the name of the service to start. This is the name that was used to create the service and you can read this name when you start the graphical service control manager application.

The subroutine returns undef value. If the service can not be paused the function raises error.

[Contents]

13. Continue a paused Windows NT service

This function asks a Windows NT service to continue after it was paused

nt::ContinueService "Service name"

The argument for this subroutine call is the name of the service to start. This is the name that was used to create the service and you can read this name when you start the graphical service control manager application.

The subroutine returns undef value. If the service can not be continued the function raises error.

[Contents]

14. Create a hard link on a file or directory

This function function establishes an NTFS hard link between an existing file/directory and a new file/directory. An NTFS hard link is similar to a POSIX hard link.

nt::HardLink "existing file","new filename"

Any directory entry for a file, is a hard link to the associated file. Additional hard links, created with the HardLink function, allow you to have multiple directory entries for a file, that is, multiple hard links to the same file. These may be different names in the same directory, or they may be the same (or different) names in different directories. However, all hard links to a file must be on the same volume.

Because hard links are just directory entries for a file, whenever an application modifies a file through any hard link, all applications using any other hard link to the file see the changes. Also, all of the directory entries are updated if the file changes. For example, if the file's size changes, all of the hard links to the file will show the new size.

When creating hard link to a directory the situation is a bit different. In these cases the original directory entry and the created links are not equivalent. If you delete the link then the original directory and its content remains untouched. However if you delete the directory any link to that directory becomes unusable.