Part Four: Software Distribution

List of Topics
19.0 BrightWorks Distribution
19.1 About BrightWorks' Software Distribution Capability
19.2 How This Part is Organized
19.3 Software Distribution Concepts
19.4 BrightWorks' Software Distribution Modules
19.4.1 BrightWorks Console/Administrative Program
19.4.2 Update Program
19.5 Distribution Configuration Options
19.5.1 Running the Update Program
19.5.2 Automating the Update Program
19.6 Quick Start to Preparation and Setup for Software Distribution
20.0 Filesets
20.1 Introduction
20.1.1 Fileset Features
20.1.2 Access to Fileset Functions
20.1.3 What's in this Chapter
20.2 The Fileset Directory
20.2.1 Defining a Fileset Directory
20.3 Creating Filesets
20.4 Managing Filesets
20.4.1 Editing Filesets
20.4.2 Renaming Filesets
20.4.3 Copying Filesets
20.4.4 Deleting Filesets
21.0 Scripts
21.1 Introduction
21.1.1 Script Features
21.1.2 Access to Script Functions
21.1.3 What's in this Chapter
21.2 Creating Scripts
21.3 Compiling Scripts
21.4 Managing Scripts
21.4.1 Editing Scripts
21.4.2 Renaming Scripts
21.4.3 Copying Scripts
21.4.4 Deleting Scripts
21.4.5 Incorporating BrightWorks Scripts
22.0 Software Distribution Script Language
22.1 Introduction
22.1.1 What's in this Chapter
22.2 Notes on Syntax
22.3 Script Functions
22.3.1 Type of Functions
22.3.2 User-defined Variables
22.4 DOS Functions
22.5 Easy System File Functions
22.6 Windows System File Functions
22.7 Miscellaneous Functions
22.8 Rules and System Variables
22.8.1 System Variables
22.8.2 String Type Rules:
22.8.3 Integer Type Rules:
22.9 DOS Error Codes
23.0 Scopes
23.1 Introduction
23.1.1 Scope Features
23.1.2 Access to Scope Functions
23.1.3 What's in this Chapter
23.2 Creating Scopes
23.3 Scope Queries
23.3.1 Creating a New Query
23.3.2 Editing a Query
23.3.3 Deleting a Query
23.3.4 Applying a Query to the Scope
23.3.5 Removing a Query from the Scope
23.3.6 Creating a Complex Query
23.4 Managing Scopes
23.4.1 Renaming Scopes
23.4.2 Copying Scopes
23.4.3 Deleting Scopes
24.0 Packages
24.1 Introduction
24.1.1 Package Features
24.1.2 Access to Package Functions
24.1.3 What's in this Chapter
24.2 Creating and Editing Packages
24.2.1 Editing Packages
24.3 Managing Packages
24.3.1 Prioritizing Packages
24.3.2 Renaming Packages
24.3.3 Activating/Deactivating Packages
24.3.4 Deleting Packages
24.4 The Package Timer
25.0 Monitoring Software Distribution
25.1 Introduction
25.1.1 Access to the Software Distribution Log
25.1.2 What's in this Chapter
25.2 The Software Distribution Log
25.2.1 Viewing Log History Details
 
 
19.0 BrightWorks Distribution 
 
Welcome to BrightWorks' distribution features which enable software and  
script distribution from a central location. 
 
NOTE:  This chapter pertains to BrightWorks. 
 
 
19.1 About BrightWorks' Software Distribution Capability 
 
BrightWorks' software distribution capabilities provide a method for  
distributing software packages and modifying workstation configuration  
files from a central location.  The software distribution features  
facilitate consistency among the workstations across your local area  
network and improve the productivity of the LAN Administrator.   
 
Distributing software and modifying workstation configuration files  
from a central location on your network allows the LAN Administrator  
to easily do the following: 
 
o  update system executables and/or drivers (e.g., operating systems,  
network drivers) 
 
o  update system files (e.g., AUTOEXEC.BAT, CONFIG.SYS, WIN.INI, network  
login script) 
 
o  install and update software on user workstations across the local  
area network 
 
NOTE:  BrightWorks' Software Distribution capabilities can be used to  
distribute software and/or scripts to any workstation in the BrightWorks  
local site (i.e., the site which identifies the Fusion program  
directory).  Sites are discussed in detail in section 13.2.1 entitled  
"Maintaining LAN Sites." 
 
 
19.2 How This Part is Organized 
 
The following table lists the chapters in this part of the BrightWorks manual: 
 
CHAPTER                         DESCRIPTION 
19.0 Introduction               Presents an overview on the use of  
				BrightWorks' software distribution  
				capabilities.  Also provides instructions  
				on running and automating the  
				distribution update program. 
 
20.0 Filesets                   Presents the procedures for managing  
				filesets, including creating, editing,  
				renaming, copying and deleting. 
 
21.0 Scripts                    Presents the procedures for managing  
				scripts, including creating, editing,  
				renaming, copying and deleting. 
 
22.0 Software Distribution      Lists the variables and rules for each  
Script Language                 function in the BrightWorks scripting  
				language. 
 
23.0 Scopes                     Presents the procedures for managing  
				scopes, including creating, editing,  
				renaming, copying and deleting; also  
				discusses creating and managing queries  
				to assist in scope definition. 
 
24.0 Packages                   Presents the procedures for managing  
				packages, including creating, editing,  
				renaming, copying and deleting. 
 
25.0 Monitoring Software        Presents the procedures for viewing and  
Distribution                    managing the Software Distribution Log  
				History. 
 
NOTE:  Because BrightWorks' software distribution capabilities are  
provided with the inventory capabilities, the procedures for generating  
distribution reports are discussed throughout Chapter 18 of this manual.  
 
 
19.3 Software Distribution Concepts 
 
An understanding of the following concepts will help you in gaining full  
advantage of BrightWorks' software distribution capabilities: 
 
o  Fileset - A file that contains one or more compressed files.   
Each compressed file may also indicate a target directory structure in  
which the file should be decompressed.  For example, assume a fileset  
named NEW_INI_FILES.  The fileset might consist of two files: WIN.INI  
and SYSTEM.INI which have been defined to be decompressed into a  
target directory named PUB\WIN.310. 
 
o  Script - A sequence of one or more commands which define an operation  
to be performed on a workstation receiving a distribution.  For example,  
a script might include the commands to add a new group to the Windows  
Program Manager, to copy file(s) from one location to another, or to  
change parameters within certain files. 
 
o  Scope - A group of one or more workstations that have been identified  
to receive a distribution.  For example, to distribute a script to all  
386 workstations, you must create a scope which includes the 386 workstations. 
 
o  Package - The distributed object which contains scheduling information,  
as well as a fileset and/or script and a scope.   
 
The package being created is named "Updated INI Files," as indicated in  
the dialog box title bar.  The package is scheduled to be distributed on  
6/30/1994.  The package consists of the fileset named "NEW_INI_FILES,"  
which will get distributed to all nodes included in the scope named  
"LOCAL NODES." 
 
The following key features help you distribute software across your LAN: 
 
o  Creating filesets which include files to be installed on remote  
workstations. 
 
o  Creating scripts to be executed by remote workstations. 
 
o  Defining scopes of workstations to receive distributed packages. 
 
o  Creating and scheduling packages which consist of a scope and one  
fileset and/or one script. 
 
o  Monitoring package progress via the Software Distribution Log History  
dialog box. 
 
 
19.4 BrightWorks' Software Distribution Modules 
 
The BrightWorks software distribution capabilities interact with two  
major functional modules.  As an introduction to software and script  
distribution, this section briefly describes the following modules: 
 
o  BrightWorks console and administrative functions 
o  Remote workstation update program (SDUPDATE.EXE) 
 
NOTE:  BrightWorks' software distribution capabilities are provided with  
the inventory capabilities discussed in Part Three of this manual. 
 
19.4.1 BrightWorks Console/Administrative Program 
 
BWORKS.EXE is the BrightWorks console and administrative program.  This  
program provides access to all BrightWorks capabilities.  This main module  
is a Windows-based program and is intended to be used by the LAN network  
manager to perform all software distribution functions. 
 
The software distribution functions available from the BrightWorks console  
include: 
o  Scope definition and management 
o  Script creation and management 
o  Package creation, scheduling and management 
o  Pre-defined and custom distribution report generation   
 
19.4.2 Update Program 
 
The update program (SDUPDATE.EXE) must be executed from each remote  
workstation to enable the workstations to receive the distributed  
packages they have been sent.  Upon BrightWorks installation, the update  
program is copied into the BWORKS program directory. 
 
The update program is DOS-based and must be executed from the machine  
which is to be updated.  To ensure that SDUPDATE.EXE is executed on a  
regular basis, the command can be placed in the system login script.   
Refer to the next section entitled "Distribution Configuration Options." 
 
NOTE:  WSDUPD.EXE is the BrightWorks update program which handles the script  
functions related to installing Windows software.  This program must not be  
directly run by the user--it is automatically loaded when the ADDGROUP,  
ADDITEM or SCHEDULEWIN Windows System File script functions are used.  Refer  
to section 22.6 entitled "Windows System File Functions." 
 
 
19.5 Distribution Configuration Options 
 
The update program SDUPDATE.EXE must be run from each workstation in  
order for it to receive the distributed packages it has been sent.   
Upon BrightWorks installation, the update program is copied into the  
BWORKS program directory.   
 
The SDUPDATE program's syntax is as follows: 
 
SDUPDATE [drive:[\path]] 
 
in which drive and path are optional parameters.  The brackets are not typed.  
 
Consider the following examples: 
 
Example                 Result 
SDUPDATE                SDUPDATE will look in the current directory. 
SDUPDATE F:             SDUPDATE will look in the current directory  
			on drive F:. 
SDUPDATE F:\path        SDUPDATE will look in the directory F:\path. 
 
 
NOTES: a - The Btrieve Record Manager must be loaded before running  
SDUPDATE.EXE.  Refer to the section entitled "Consider Improving  
BrightWorks' Database Performance" in Chapter 12 of this manual for a  
discussion on the Btrieve options. 
b - When running the Brequestor, BSPXCOM and BROUTER must also be loaded  
on the file server.  For details on loading these programs, refer to  
your Novell documentation. 
c -  When running SDUPDATE.EXE in a DOS box, you must load another  
session of BREQUEST by entering the following command: 
 
	 BREQUEST /D:17000 /L 
 
After running SDUPDATE, end the additional session by issuing the  
ENDBTRV command. 
 
19.5.1 Running the Update Program 
 
Use the following procedure to manually run the update program at a  
workstation. 
 
1.  At the workstation which is to receive the distributed package, load  
    the Btrieve Record Manager. 
 
    Either Btrieve or Brequest can be used.  Refer to section 12.6.3 entitled  
    "Consider Improving BrightWorks' Database Performance" for a discussion  
    on the Btrieve options. 
 
2.  Make the BrightWorks directory your current directory. 
 
    Use the DOS CD command to change into the BWORKS program directory,  
    or map a physical drive to the BWORKS directory. 
 
3.  Execute the SDUPDATE.EXE program. 
 
    For example, enter the following at the DOS command line: 
 
	SDUPDATE 
 
    Upon executing SDUPDATE, several messages will display at the workstation.   
    If the user has not been given the option to refuse the update or  
    change the installation path, then the update program will continue  
    automatically (e.g., the package's script or fileset will be installed 
    at the workstation). 
 
    a. If you are given the option of refusing the package, then the  
    prompt displays.  To install the package at this time, type <Y>.   
    To install the package another time (e.g., the next time the update  
    program is run), type <N>. 
 
    NOTE:  If the date or maximum number of times has expired and the  
    package is configured to 'force upgrade,' then the package will be  
    installed regardless of the user's response to this prompt. 
 
    b. If you are given the option of overriding the installation path,  
    then the prompt displays.  To override the default installation path,  
    type <Y>.  To accept the default installation path, type <N>.  If  
    you type <Y> to override the default installation path, you are  
    prompted to specify a new installation path.  Type the new path and  
    press the <ENTER> key.  The update program continues, and the package  
    is installed. 
 
19.5.2 Automating the Update Program  
 
To ensure that SDUPDATE is executed on a regular basis, the command can  
be placed in the system login script.   
 
The following example illustrates SDUPDATE being executed from within  
the system login script.  (Refer section 35.0 for instructions on  
configuring the Btrieve NLM or VAP.) 
 
.... 
MAP G:=SERVER/SYS:FUSION 
DRIVE G: 
#BREQUEST /D:17000 
#SDUPDATE 
#ENDBTRV 
.... 
 
where G:=SERVER/SYS:FUSION is the drive ID and complete path where the  
BrightWorks files and update program are stored. 
 
 
19.6 Quick Start to Preparation and Setup for Software Distribution 
 
This section provides the steps necessary to successfully distribute software. 
 
1.  Create a FILESET which will include files to be installed on the remote 
    workstation. 
 
    For example, the FILESET might include the following files necessary to 
    update the PC to run Windows: LAN Driver, IPXODI, LSL, NETX, HIMEM, 
    SMARTDRIVE, EMM286 & MOUSE. 
 
    See section 20.3 entitled "Creating Filesets." 
 
2.  Create SCRIPTS to be executed by remote workstations or modify canned 
    scripts to meet your needs to complete certain tasks. 
 
    See section 21.4.5 entitled "Incorporating BrightWorks' Scripts." 
    The following files are specifically recommended: 
	a. AUTORLP.SCR replaces the AUTOEXEC.BAT file. 
	b. CFGRPLMT.SCR replaces the CONFIG.SYS file. 
	c. WININST.SCR Windows Network Installation. 
	NOTE: These scripts will require minor modifications to meet your 
	specific environment requirements (e.g., drive mappings, local  
	Windows install, etc.). 
 
3.  Define SCOPES of workstation to receive distributed packages. 
 
    See section 23.2 entitled "Creating Scopes." Apply queries to scopes 
    (e.g., who will receive the packages based on a criteria). See section 
    23.3 entitled "Scope Queries." 
 
4.  Create and schedule PACKAGES which will consist of a scope, a fileset, 
    and/or one script. 
 
    See section 24.2 entitled "Creating and Editing Packages." 
 
5.  Run SDUPDATE from the System Login Script to distribute the PACKAGE. 
 
    Suggested method: 
	MAP F:=SERVER\VOL:BWORKS 
	DRIVE F: 
	#BREQUEST /D:17000 
	#SDUPDATE 
	#ENDBTRV 
	MAP DEL F: 
 
    See section 19.5 entitled "Distribution Configuration Options." 
 
6.  Monitor Software Distribution by viewing the Distribution Log. 
 
    The history log provides a summary of all scheduled packages. See  
    section 25.2 entitled "The Software Distribution Log." 
 
 
 
20.0 Filesets 
 
Chapter 19 provided an introduction to BrightWorks' software distribution  
capability.  This chapter discusses the creation and management of  
filesets--the set of files to be installed on a remote workstation. 
 
NOTE:  This chapter pertains to BrightWorks. 
 
 
20.1 Introduction 
 
A fileset is a set of files, stored in compressed format, to be installed  
on a remote workstation.  Distributing filesets from a central location  
simplifies a System Administrator's job.  Instead of physically moving  
from workstation to workstation to install or upgrade application files, the  
Administrator only needs to centrally distribute one fileset consisting  
of the application files.  Upon receipt at a remote workstation, the  
fileset contents are decompressed and copied onto the workstation's  
hard drive.   
 
20.1.1 Fileset Features 
 
In addition to containing a number of files to be distributed, filesets  
can be defined to create a target directory structure.  For example, if  
you create a fileset which includes all files for Windows 3.1, you must  
also define the contents of the SYSTEM subdirectory.  BrightWorks  
can do this for you automatically by including the full path name of  
every file included in the fileset.  
 
Filesets and scripts are a powerful combination.  Consider the following  
examples: 
 
o  Packaging the latest WIN.INI file with a script which determines  
whether the existing WIN.INI file is outdated.  The script will also  
copy the new WIN.INI if an old file is detected. 
 
o  Packaging the Novell IPXODI files and sending them to the scope of  
nodes using IPX.  After the fileset is decompressed in the target  
directory, the script will update the AUTOEXEC.BAT file to reflect the  
use of IPXODI.  
 
Filesets can be stored, used and reused as a resource within BrightWorks.   
An administrator can create a new fileset, as well as edit, copy, rename  
and delete a fileset.  The steps for each procedure are provided in this  
chapter. 
 
20.1.2 Access to Fileset Functions 
 
Most fileset functions are accessed by choosing the Filesets command  
from the Tools menu.  The Filesets dialog box displays listing all  
available filesets. 
 
The process of defining a directory in which filesets are saved (the  
"default fileset directory") is performed by choosing the Distribution  
command from the Administration menu.  From the sub-menu that displays,  
choose the Preferences command.  
 
20.1.3 What's in this Chapter 
 
The following chart describes the sections in this chapter: 
 
SECTION                         DESCRIPTION 
The Fileset Directory           Discusses the fileset directory,  
				and describes the procedures for its  
				definition. 
 
Creating Filesets               Describes procedures for defining new  
				filesets. 
 
Managing Filesets               Describes procedures for editing, renaming,  
				copying and deleting filesets. 
 
 
20.2 The Fileset Directory 
 
The fileset directory defines the path in which filesets are stored.   
Upon saving a fileset, a copy of the files that are included in the  
fileset are compressed.  They are stored in a file which is placed in the  
fileset directory defined at the time the fileset is saved.  For example,  
if your fileset directory is defined as F:\FUSION\FILESETS, then the  
filesets that you create will be stored in the F:\FUSION\FILESETS directory. 
 
20.2.1 Defining a Fileset Directory 
 
Use the following procedure to define the directory in which filesets  
should be stored. 
 
1.  Choose the Distribution command from the Administration menu.  From  
    the sub-menu that displays, choose the Preferences command. 
 
    The Preferences dialog box displays. 
 
2.  Choose the Browse button to define the pathname into which the  
    compressed filesets are to be stored. 
 
    The Path Browse dialog box displays enabling you to select from  
    the lists of Drives and Directories.  Click on the Drives and  
    Directories fields to select the desired pathname. 
 
3.  When the pathname is selected, choose the OK button. 
 
    The Path Browse dialog box closes, and the selected pathname displays  
    in the Path to Filesets field of the Preferences dialog box. 
 
4.  Choose the Save button to define the fileset directory. 
 
    All saved filesets will be stored in the defined directory. 
 
NOTE:  The fileset directory instructs the update program as to where  
the filesets are located.  As a result, changing the fileset directory  
after you have created filesets and included them in packages can  
invalidate those packages.  If you change the default directory, you must  
also copy all fileset files (*.SET) into the new fileset directory.   
Be sure that each user has the same drive letter mapped to the same  
server/volume specified in the Preferences dialog box.  Also, you cannot  
store filesets on a non-network drive. 
 
 
20.3 Creating Filesets 
 
Use the following procedure to create a new fileset. 
 
1.  Choose the Filesets command from the Tools menu. 
 
    The Filesets dialog box displays listing the names of all defined  
    filesets.   
 
2.  Choose the New button. 
 
    The New Fileset dialog box displays prompting you to enter a name  
    for the new fileset.   
 
3.  Enter the new fileset name, and choose the OK button. 
 
    A fileset name can be up to 80 characters, and all typed characters  
    are valid. 
 
    Upon choosing the OK button, the Edit Fileset dialog box displays  
    prompting you to define the contents of the new fileset.   
 
    The fileset name being created or edited displays in the title bar of  
    the Edit Fileset dialog box. The name of the fileset being created  
    is "1994 Budget Files." 
 
    For each file included in the fileset, the following information displays:  
    File Name, Original Size, Compression Ratio, Date, Time, and Path.  The  
    file list area is empty for new filesets.   
 
    The Filename field in this dialog box displays the name of the file  
    which will hold the compressed fileset. Upon saving the fileset, a  
    compressed copy of all of the listed files will be stored in the file  
    named "1994BUDG.SET."  This file is automatically created by BrightWorks  
    when the fileset is created.  It is stored in the fileset directory  
    which is currently defined. 
 
4.  To add a file to the fileset, choose the Add button. 
 
    The Add File dialog box displays.  This dialog box is a standard  
    Windows dialog box used for opening, selecting and browsing files.   
 
5.  Make selections from the Directories and Drives lists to find the file(s)  
    to include in the fileset.  
 
    For example, choose the Drives down arrow button, and click on Drive C:  
    to display the directories on drive C.  From the list of directories  
    which displays, click on one to display its file list. 
 
6.  Select a file(s) from the File Name list. 
 
    Multiple files can be selected using the Windows extended select  
    procedures (i.e., hold down the <CTRL> or <SHIFT> key while selecting  
    files). 
 
7.  To include the selected file(s)' path in the Edit Fileset dialog box,  
    enable the Include Path option. 
 
    Placing a checkmark in this field causes the full pathnames of each  
    selected file to be listed in the Edit Fileset dialog box.  (Step #9  
    below provides the option to instruct the fileset to create the  
    directory structure at the receiving workstation.) 
 
8.  Choose the OK button. 
 
    Upon choosing the OK button, the selected files are listed in the Edit  
    Fileset dialog box.  Only the File Name and Path information display  
    at this time.  The other fields are not available until the fileset is  
    saved. 
 
9.  Enable or disable the Create Directory Structure option. 
 
    Enabling this option causes the full pathnames of each file listed in  
    the Edit Fileset dialog box to be created at the receiving workstation.   
    For example, assume that this option is enabled and a file is listed in  
    the Edit Fileset dialog box as \USER\MARY\INVOICE.DOC.  In this  
    case, the directories USER and MARY will be created at the receiving  
    workstation if they do not already exist. 
 
NOTE:  A fileset is always decompressed into the target directory that  
is specified when creating a package.  In the above example, if the Create  
Directory Structure option is checked and the fileset is included in a  
package that has a default path of C:\SALES, then the INVOICE.DOC file  
will be decompressed into C:\SALES\USER\MARY. 
 
10. To save the fileset contents, choose the Save button. 
 
    The changes made to a fileset are only committed to upon choosing the  
    Save button.  The Updating Fileset dialog box displays while the  
    fileset contents are being saved and compressed.  If you attempt to  
    close the Edit Filesets dialog box without saving, you are prompted to  
    save the fileset changes. 
 
    The fileset is created and added to the Filesets dialog box. 
 
 
20.4 Managing Filesets 
 
This section describes the procedures for editing, renaming, copying and  
deleting filesets. 
 
20.4.1 Editing Filesets 
 
Editing a fileset may become necessary in order to add or delete a  
file according to a change in a fileset's intent. 
 
NOTE:  It is recommended that you temporarily deactivate any packages  
which use the fileset you intend to edit. 
 
Use the following procedure to edit the contents of a fileset.  The  
procedure assumes that you have already chosen the Filesets command from  
the Tools menu to display the Filesets dialog box. 
 
1.  Select the fileset from the list of Filesets, and choose the Edit button. 
 
    A fileset can also be selected for editing by double clicking on the  
    fileset name in the Filesets dialog box.  The Edit Fileset dialog box  
    displays listing all files included in the fileset.  
 
    For each file in the fileset, the following information displays: 
 
	o  File Name - the name of the file 
	o  Original Size - the file size before compression 
	o  Compressed Size - the file size after compression 
	o  Ratio - the compression ratio 
	o  Date - the file's creation date 
	o  Time - the file's creation time 
	o  Path - the file's path which displays only if the Include Path  
	option is checked in the Add File dialog box. 
 
NOTE:  Some files may show a 0% compression ratio.  This occurs when the  
file is already compressed or when the file is very small. 
 
2.  To add a file to the fileset, choose the Add button. 
 
    The Add File dialog box displays.  Refer to the section above entitled  
    "Creating Filesets" for detailed procedures on using this dialog box. 
 
3.  To delete a file from the fileset, highlight the file name and choose  
    the Delete button.  
 
    A prompt displays asking you to confirm the deletion.  Choose the Yes  
    button to continue with the delete action. 
 
    If deleted, the file name is removed from the Edit Filesets dialog box.   
 
4.  To save the edited fileset contents, choose the Save button. 
 
    The changes made to a fileset are only committed to upon choosing the  
    Save button.  The Updating Fileset dialog box displays while the  
    fileset contents are being saved and compressed.  If you attempt to  
    close the Edit Filesets dialog box without saving, you are prompted to  
    save the fileset changes. 
 
20.4.2 Renaming Filesets 
 
Changing the name of an existing fileset renames all instances of the  
former fileset name.  For example, the new fileset name is reflected in  
the Filesets dialog box as well as in any packages which include the fileset. 
 
Use the following procedure to rename a fileset.  The procedure assumes  
that you have already chosen the Filesets command from the Tools menu to  
display the Filesets dialog box. 
 
NOTES: a - A fileset can be renamed even if it is part of an actively  
scheduled package. 
b - The name of the .SET file which is maintaining the compressed fileset  
and is stored in the fileset directory does not change.  
 
1.  To rename a fileset, select the fileset name from the list of Filesets,  
    and choose the Rename button. 
 
    The Rename Fileset dialog box displays prompting you to enter a new  
    fileset name. 
 
2.  Enter the new fileset name, and choose the OK button. 
 
    The new fileset name displays in the Filesets dialog box, and the  
    old name is removed.  All attributes of the old fileset are preserved  
    in the renamed fileset (i.e., the fileset contents do not change). 
 
20.4.3 Copying Filesets 
 
Use the following procedure to copy a fileset.  The procedure assumes that  
you have already chosen the Filesets command from the Tools menu to display  
the Filesets dialog box. 
 
NOTE:  A fileset can be copied even if the original fileset is part of  
an actively scheduled package. 
 
1.  To copy a fileset, select the fileset name from the list of Filesets,  
    and choose the Copy button. 
 
    The Copy Fileset dialog box displays prompting you to enter a name  
    for the new fileset. 
 
2.  Enter the new fileset name, and choose the OK button. 
 
    The new fileset name is added to the Filesets dialog box.  The new  
    fileset contents are identical to the original fileset contents. 
 
20.4.4 Deleting Filesets 
 
Use the following procedure to delete a fileset.  The procedure assumes  
that you have already chosen the Filesets command from the Distribution  
menu to display the Filesets dialog box. 
 
NOTE:  A fileset that is part of a scheduled package cannot be deleted. 
 
1.  To delete a fileset, select the fileset from the list of Filesets,  
    and choose the Delete button. 
 
    A prompt displays asking you to confirm the deletion. 
 
2.  Choose the Yes button to delete the fileset. 
 
    The fileset name is removed from the Filesets dialog box.   
 
 
 
21.0 Scripts 
 
Chapter 20 discussed the creation and management of filesets.  This  
chapter discusses the creation and management of scripts--a series  
of commands to be executed on a remote workstation. 
 
NOTE:  This chapter pertains to BrightWorks. 
 
 
21.1 Introduction 
 
A script is a series of commands to be executed on a remote workstation.   
Scripts must be written according to a defined syntax, and they must be  
compiled successfully to be included in a package.   
 
NOTES: a - The commands and instructions for using BrightWorks' software  
distribution scripting language are documented in Chapter 22 of this  
manual. 
b - BrightWorks is shipped with several script files that can be  
customized for your own use. Refer to section 21.4.5 entitled "Incorporating  
BrightWorks Scripts."  
 
21.1.1 Script Features 
 
The ability to send scripts from a central location can be used to  
contribute to the consistency and standardization of LAN workstations.   
Scripts enable the LAN administrator to easily do the following: 
 
o  update system executables and/or drivers (e.g., operating systems,  
network drivers) 
 
o  update system files (e.g., AUTOEXEC.BAT, CONFIG.SYS, WIN.INI,  
network login script) 
 
o  install software on a user's workstation 
 
A user can create a new script, as well as edit, compile, copy, rename  
and delete a script.  The steps for each procedure are discussed in this  
chapter.   
 
21.1.2 Access to Script Functions 
 
Script functions are accessed by choosing the Scripts command from the  
Tools menu.  The Scripts window displays listing all available scripts.   
 
Script management is performed by either choosing the buttons in the  
Scripts window or by choosing the corresponding commands from the File menu.   
For example, when the Scripts window is active, a new script can be  
created either by choosing the New button in the Scripts window or by  
choosing the New Script command from the File menu.   
 
The Edit menu commands provide the standard Cut, Copy and Paste functionality  
for use during script editing. 
 
21.1.3 What's in this Chapter 
 
The following chart describes the sections in this chapter: 
 
SECTION                 DESCRIPTION 
Creating Scripts        Describes procedures for defining new scripts. 
 
Compiling Scripts       Describes the procedures for compiling scripts. 
 
Managing Scripts        Describes procedures for editing, renaming,  
			copying and deleting scripts. 
 
		      
21.2 Creating Scripts 
 
A script is created by assigning both a script name and a file name to  
the new script.  The script name is used for identification purposes  
within BrightWorks.  For example, it is immediately obvious that the  
script named "Upgrade to Win 3.1" is responsible for upgrading the  
Windows software to version 3.1.  The script file name identifies the  
ASCII text file containing the script commands.  The script file name  
must be a valid DOS file name (e.g., 8 characters plus the 3 character  
extension). 
 
After assigning the script name and file name, an "empty" script is created.   
The empty script must be edited in order to add commands.   
 
Use the following procedure to create a new script. 
 
1.  Choose the Scripts command from the Tools menu. 
 
    The Scripts window displays listing the names of all defined scripts.   
    For each script, the last compilation date, the status and the file name  
    also displays. 
 
2.  Choose the New button. 
 
    The Open New Script dialog box displays prompting you to enter the  
    name, file name and destination directory for the new script.   
 
3.  Enter the new script information, and choose the OK button. 
 
    The script name can be up to 80 characters, and all typed characters  
    are valid.  The script file name must follow the standard DOS conventions. 
 
NOTES: a - It is recommended that .SCR be assigned as the extension for  
all script file names.  A script file is a text file and can be edited  
with an external editor. 
b - The scripts must reside on a network drive to which all users who will  
receive the script have access 
 
Upon choosing OK, the message "This file does not exist.  Create the file?"  
displays.  Choose the Yes button to create the script file and display the  
Script Editor window. 
 
The script name being edited displays in the title bar of the Script Editor  
window.  All commands that are included in this script are listed.  (The  
list is empty for new scripts.) 
 
4.  Type the script commands. 
 
    Script commands can be directly typed into the Script Editor window.   
    Commands can also be selected from a list of commands by choosing the  
    Functions button in the Script Editor window or the Paste Script  
    Function command from the BrightWorks Edit menu (refer to the  
    explanation below). 
 
    The script compiler requires one command per line.  No error checking  
    is performed until the script is compiled. 
 
    Optional comments can be placed in the script preceded by a semi-colon.   
    These comments are ignored at compile time.  For example: 
 
	;This is a comment. 
 
NOTE:  The commands and rules for using the scripting language are  
documented in Chapter 22 of this manual, "Software Distribution Script  
Language." 
 
Standard editing functions are available from the Edit menu on the  
BrightWorks menu bar.  The commands that are available from the Edit menu  
are as follows: 
 
o  Undo - removes the last change made to the script. 
 
o  Cut - copies a block of selected text to the clipboard and removes the  
text from the Script Editor window. 
 
o  Copy - copies a block of selected text to the clipboard. 
 
o  Paste - places the block of text from the clipboard into the Script  
Editor window at the current cursor location. 
 
o  Paste Script Function - displays the Choose Script Function dialog box.   
This dialog box allows you to select a function (from a list of all script  
functions) to be placed in the script at the current cursor location.  A  
function can be selected by either double clicking on the function name,  
or highlighting the name and choosing the OK button.  Choosing the Help  
button displays help text for the highlighted function. 
 
o  Find - searches the script for a user-specified text string. 
 
o  Next - searches the script for the next occurrence of the user-specified  
text string. 
 
o  Replace -  searches the script for a user-specified text string and  
replaces the found text with another user-specified text string. 
 
o  Fonts - enables you to select the font, style and size of the script type. 
 
NOTE:  During script editing, the status bar in the BrightWorks application  
window indicates the current line and column position of the typing cursor. 
 
5.  To compile the script, choose the Compile button in the Script Editor  
    window. 
 
    Refer to the next section for details on compiling scripts. 
 
6.  To save the script contents, choose the Save button in the Script  
    Editor window. 
  
    The saved script contents are stored in ASCII text format.  The script  
    must be compiled to be used in a package.  To compile the script, follow  
    the procedure below entitled "Compiling Scripts." 
 
7.  Choose the Close button to close the Script Editor window. 
 
    If you did not save the script changes as in Step #6 above, you are  
    prompted to do so now.  Choose the Yes button to save the script changes,  
    or choose No to close the Script Editor without saving any changes. 
 
    The new script is added to the Scripts window.  The status of all  
    uncompiled scripts is 'ASCII.'   A script must be compiled to be used  
    in a package. 
 
 
21.3 Compiling Scripts 
 
The Status field in the Scripts window indicates the status of each script.   
Script status can be either ASCII or COMPILED.  A script's status must be  
COMPILED to be used in a package for distribution. 
 
The commands and instructions for using the scripting language are documented  
in Chapter 22 of this manual, "Software Distribution Script Language."   
The compilation process checks the syntax and validity of the script's  
commands. 
 
Use the following procedure to compile a script.  The procedure assumes  
that you have already chosen the Scripts command from the Tools menu to  
display the Scripts window. 
 
1.  To compile a script, select the script in the Scripts window and  
    choose the Compile button. 
 
    While a compile is in progress, the Compile Status dialog box displays.   
 
    When the compile is complete, the Status field in the Compile Status  
    dialog box indicates success or failure.  If the compile fails, the  
    Function field indicates the first function found which has invalid  
    parameters.  The Statistics area indicates the total number of lines in  
    the script (Lines field) and the number of errors found (Errors field). 
 
2.  Choose the OK button to continue. 
 
    If the script compile is successful, then choose the Close button in  
    the Script Editor window to return to the Scripts window which shows  
    the script's status as COMPILED. 
 
    If the script compile fails, then the Compiler Messages dialog box  
    displays listing the first script line which contains errors. 
 
3.  To correct a compiler error condition, double click on an error line  
    in the Compiler Messages dialog box. 
 
    The Script Editor window displays with the script that you are  
    attempting to compile.  The selected error line is automatically  
    highlighted. 
 
4.  Correct all error conditions, and attempt to re-compile the script. 
 
    Refer to Chapter 22 of this manual for details on the scripting rules  
    and commands. 
 
    After successful compilation of the script, the script can be used  
    in a package. 
 
NOTE:  If you edit a script that has already been compiled, the script  
must be successfully re-compiled in order to be used in a package.   
Refer to the "Last Comp" field in the Scripts window to discover the date  
on which the file was last compiled. 
 
 
21.4 Managing Scripts 
 
21.4.1 Editing Scripts 
 
Editing a script may be necessary under two circumstances: 
 
o  Existing scripts might need to be edited in order to add or delete  
commands according to a change in a script's intent. 
 
o  When a script compilation fails, the script must be edited to resolve  
the error(s). 
 
NOTE:  It is recommended that you temporarily deactivate any packages  
which use the script you intend to edit. 
 
Use the following procedure to edit the contents of a script.  The  
procedure assumes that you have already chosen the Scripts command from  
the Tools menu to display the Scripts window. 
 
1.  Select the script from the Scripts window, and choose the Edit button. 
 
    A script can also be selected for edit by double clicking on the script  
    name in the Scripts window.  The Script Editor window displays. 
 
    The script name being edited displays in the title bar of the Script  
    Editor window.  All commands that are included in this script are listed. 
 
2.  Edit the script commands. 
 
    Script commands can be directly typed into the Script Editor window.   
    Commands can also be selected from a list of commands by choosing the  
    Functions button in the Script Editor window or the Paste Script Function  
    command from the BrightWorks Edit menu. 
 
    The script compiler requires one command per line.  No error checking is  
    performed until the script is compiled. 
 
NOTES: a - The commands and rules for using the scripting language are  
documented in Chapter 22 of this manual, "Software Distribution Script  
Language." 
b - During script editing, the status bar in the BrightWorks application  
window indicates the current line and column position of the typing cursor. 
 
3.  To compile the script, choose the Compile button in the Script Editor  
    window. 
 
    Refer to section 21.3 entitled "Compiling Scripts" for details on  
    compiling scripts. 
 
4.  To save the edited script contents, choose the Save button in the  
    Script Editor window. 
 
5.  Choose the Close button to close the Script Editor window. 
 
NOTE:  If you edit a script that has already been compiled, the script  
must be successfully re-compiled in order to be used in a package. 
 
21.4.2 Renaming Scripts 
 
Changing the name of an existing script renames all instances of the  
former script name.  For example, the new script name will be reflected  
in the Scripts window as well as in any packages which include the script. 
 
Use the following procedure to rename a script.  The procedure assumes  
that you have already chosen the Scripts command from the Tools menu to  
display the Scripts window. 
 
NOTE:  A script can be renamed even if it is part of an actively scheduled  
package. 
 
1.  To rename a script, select the script name from the Scripts, and choose  
    the Rename button.  
 
    The Rename Script dialog box displays prompting you to enter a new  
    script name. 
 
2.  Enter the new script name, and choose the OK button. 
 
    The new script name displays in the Scripts window, and the old name  
    is removed.  All attributes of the old script are preserved in the  
    renamed script (i.e., the script contents do not change). 
 
NOTE:  The script rename procedure only changes the script name--the script  
file name does not change. 
 
21.4.3 Copying Scripts 
 
Use the following procedure to copy a script.  The procedure assumes that  
you have already chosen the Scripts command from the Tools menu to display  
the Scripts window. 
 
NOTE:  A script can be copied even if the original script is part of an  
actively scheduled package. 
 
1.  To copy a script, select the script from the Scripts, and choose the  
    Copy button.  
 
    The Copy Script dialog box displays prompting you to specify a name,  
    file name and destination directory for the new script.  The script  
    name can be up to 80 characters, and all typed characters are valid.   
    The script file name must follow the standard DOS conventions and can  
    reside in any directory. 
 
NOTE:  It is recommended that .SCR be assigned as the extension for all  
script file names. 
 
2.  Enter the new script information, and choose the OK button. 
 
    The new script name is added to the Scripts window.  The new script is  
    populated with the same commands as the original script. 
 
21.4.4 Deleting Scripts 
 
Use the following procedure to delete a script.  The procedure assumes that  
you have already chosen the Scripts command from the Tools menu to display  
the Scripts window. 
 
NOTE:  A script that is part of a scheduled package cannot be deleted. 
 
1.  To delete a script, select the script from the Scripts, and choose the  
    Delete button.   
 
    A prompt displays asking you to confirm the deletion. 
 
2.  Choose the Yes button to delete the script. 
 
    If deleted, the script name is removed from the Scripts window.   
 
NOTE:  The delete action only deletes the script name from the Scripts  
window.  The corresponding .SCR file is not deleted.  Therefore, if a script  
name is inadvertently deleted, you can create a new script and assign the  
same script file name to retrieve the deleted script contents. 
 
21.4.5 Incorporating BrightWorks Scripts 
 
BrightWorks is shipped with several pre-defined scripts that can be  
customized for use in your environment.  Upon BrightWorks installation, the  
script files are copied into the BWORKS program directory.   
 
The table below lists the purpose of each script and indicates the script  
file name: 
 
PURPOSE                                 FILE NAME 
Word for Windows Local Installation     LOCAL.SCR 
Find and Delete a Program File          FINDDEL.SCR 
AUTOEXEC.BAT Replacement                AUTORLP.SCR 
AUTOEXEC.BAT Append                     AUTOAPP.SCR 
AUTOEXEC.BAT Modification               AUTOMOD.SCR 
CONFIG.SYS Replacement                  CFGRPLMT.SCR 
CONFIG.SYS Append                       CFGAPP.SCR 
CONFIG.SYS Modification                 CFGMOD.SCR 
DOS Upgrade 3.X to 6.X                  DOS3TO6.SCR 
DOS Upgrade 4.X to 5.X                  DOS4TO5.SCR 
DOS Upgrade 5.X to 6.X                  DOS5TO6.SCR 
Novell NETX Update                      NETXUP.SCR 
Novell Wkst ODI/VLM/IPX Driver          NETBAT.SCR  
Startup Batch File Update         
VLM Upgrade                             VLMUPGRD.SCR 
Send Text Message to Network Users      TYPE.SCR 
Copy Files to Server                    CPFS.SCR 
Windows Network Installation            WININST.SCR 
Windows Add Program Group               ADDGROUP.SCR 
Windows Add Program Item                ADDITEM.SCR 
Windows INI Replacement                 INIRPL.SCR 
Windows INI Append                      WINIAPPD.SCR 
Windows INI Modification                WININIMD.SCR 
Windows Spooler Setting in INI          WINSPOOL.SCR 
Install SMRAGENT.EXE                    AGENT.SCR 
Windows Wallpaper Update                WALLPAPR.SCR 
CC:MAIL for Windows installation        NETINS.SCR 
 
Use the following procedure to incorporate a pre-defined script into  
BrightWorks. 
 
1.  Choose the Scripts command from the Tools menu. 
 
    The Scripts window displays. 
 
2.  Choose the New button. 
 
    The Open New Script dialog box displays.   
 
3.  Enter a name for the script in the Script Name field. 
 
    The script name can be up to 80 characters, and all typed characters  
    are valid.  The script name is used within BrightWorks to identify the  
    script.  For example, if you are incorporating the script which adds a  
    group to the Program Manager desktop, then you might want to define  
    the script name as ADD PROGRAM GROUP. 
 
4.  Select the script to be incorporated into BrightWorks. 
 
    Select a script from the list of script file names.  For example, if  
    you want to incorporate and edit the script which adds a group to the  
    Program Manager desktop, then you would select the ADDGROUP.SCR file. 
 
5.  Choose the OK button. 
 
    The Script Editor window displays listing the commands for the chosen  
    script. 
 
6.  Edit the script commands. 
 
    The commands and rules for using the scripting language are documented  
    in Chapter 22 of this manual, "Software Distribution Script Language." 
 
7.  Choose the Compile button in the Script Editor window to compile the  
    script. 
 
    Refer to section 21.3 entitled "Compiling Scripts" for details on  
    compiling scripts. 
 
8.  Choose the Save button in the Script Editor window. 
 
    The script contents are saved. 
 
9.  Choose the Close button to close the Script Editor window. 
 
    The new script is added to the Scripts window.  Note that a script  
    must be compiled to be used in a package. 
 
 
 
22.0 Software Distribution Script Language 
 
Chapter 21 discussed creating and managing scripts. This chapter lists the  
variables and rules for each function in the BrightWorks scripting language. 
 
NOTE:  This chapter pertains to BrightWorks. 
 
 
22.1 Introduction 
 
A script is a series of commands to be executed on a remote workstation.   
Scripts must be written according to a defined syntax, and they must be  
compiled successfully to be included in a package. 
 
The commands and instructions for using the BrightWorks software distribution  
scripting language are discussed in this chapter.  The procedures for  
creating, compiling and managing scripts are discussed in the Chapter 21  
entitled "Scripts." 
 
22.1.1 What's in this Chapter 
 
The following chart describes the sections in this chapter: 
 
SECTION                         DESCRIPTION 
Notes on Syntax                 Discusses several items to note regarding  
				the general format of the script language  
				functions. 
 
Script Functions                Discusses the type of functions available,  
				and summarizes their parameters and purpose. 
 
DOS Functions                   Lists each DOS function, providing the  
				following: the function parameters, a  
				description, tips for using the function,  
				its return values and an example for using  
				the function in a script. 
 
Easy System File Functions      Lists each Easy System File function,  
				providing the same information as above. 
 
Windows System File Functions   Lists each Windows System File function,  
				providing the same information as above. 
 
Miscellaneous Functions         Lists each Miscellaneous function, providing  
				the same information as above. 
 
Rules and System Variables      Lists the allowable values for each  
				parameter, and defines the variable rules. 
 
DOS Error Codes                 Lists the DOS error codes that can be  
				returned from the script functions. 
 
 
				 
22.2 Notes on Syntax 
 
The following items must be noted when writing scripts: 
 
o  Only one command can be placed on a line. 
 
o  The syntax for each command/function is as follows: 
 
	FUNC_NAME [parameter1], [parameter2], ...[parameterN] 
 
o  Unless otherwise noted, each function returns a 0 if it is successful  
(i.e., the system variable [retval] is set to 0).  The action to be taken  
as a result of a script's return code is defined when the script is  
included in a package.  These "Advanced Package Options" are discussed in  
Chapter 24.  
 
o  Some functions take "optional" parameters.  The administrator should 
decide whether or not to specify these parameters. If they  
are not specified, an empty or NULL value must be passed to the compiler to  
act as a placeholder. 
 
For example, the COPY function has the following parameters: 
 
	COPY [path] [filewild] [path] {filewild} 
	 
where the last parameter, {filewild}, is optional.  The COPY command below  
provides an example for copying all .BAT files from the C: drive to the B:  
drive, using a placeholder to stand for the last {filewild} parameter:  
 
	COPY "C:\" "*.BAT" "B:\" ""  
 
In this example, the files are not renamed and retain their original .BAT  
extensions. 
 
 
22.3 Script Functions 
 
Each script "command" is treated as a "function" (e.g., a C function) that  
has two basic properties:  
 
o  each command has 0 to 4 parameters that it will be passed 
o  most commands have a return code   
 
As such, the script language supports user defined variables (of integer  
and string type), as well as "system" variables.  When necessary, the  
functions also implement return values from the parameters that are passed. 
 
Each function has one or more parameters that can be passed.  In the  
following discussions, the required parameters are surrounded by [ ], and  
the optional parameters are surrounded by {  }.  Each parameter is the  
name of a rule, whose allowable values are listed later in this chapter. 
 
22.3.1 Type of Functions 
 
The script functions are divided into the four major categories summarized  
below: 
 
DOS Functions (section 22.4): 
FUNCTION        REQUIRED PARAMETERS             DESCRIPTION 
ATTRIB          [path] [filewild] [attribute]   Changes the attributes of a  
						file or multiple files. 
 
COPY            [path] [filewild] [path]        Copies a file or files to  
		{filewild}                      another directory and file  
						name(s). 
 
DELETEDIR       [path] [filename] {deleteopt}   Deletes a directory. 
 
DELETEFILE      [path] [filewild]               Deletes a file or multiple  
						files. 
FINDFILE        [path] [filewild] [strvar]      Finds a file. 
 
MDIR            [path] [filename]               Creates a directory. 
 
RENAME          [path] [filewild] [path]        Renames a source file(s). 
		[filewild] 
 
UPGRADEOS       [upgopt]                        Upgrades DOS version from  
						3.x-5.x to either 5.00  
						or 6.00. 
 
 
Easy System File Functions (section 22.5): 
 
FUNCTION        REQUIRED PARAMETERS             DESCRIPTION 
ADDDEVICE       [strvalue1] [strvalue2]         Adds a new DEVICE= line to a  
		[addopt]                        system file. 
 
ADDLINE         [strvalue1] [strvalue2]         Adds a line of text to a  
		[addopt]                        system file. 
 
ADDPATH         [strvalue1] [strvalue2]         Adds a sub-directory to a  
		[strvalue3] [addopt]            path environment variable. 
 
CFGGETVALUE     [strvalue] [intvar]             Gets a numeric variable from  
						a system file. 
 
CFGSETVALUE     [strvalue] [intvalue]           Sets a numeric variable in a  
						system file. 
						 
CFGGETSTRING    [strvalue] [strvar]             Gets a string variable from  
						a system file. 
 
CFGSETSTRING    [strvalue1] [strvalue2]         Sets a string variable in a  
						system file. 
 
REPLACEKEY      [strvalue1] [strvalue2]         Replaces a key value in a  
		[strvalue3]                     system file. 
 
REPLACELINE     [strvalue1] [strvalue2]         Replaces an existing line in  
						a system file with a new line. 
 
REPLACELINE-ADD [strvalue1] [strvalue2]         Replaces or adds an existing  
		[addopt]                        line in a system file. 
 
SETSYSFILE      [path] [filename]               Sets a system file to be  
						manipulated. 
 
 
Windows System File Functions (section 22.6): 
 
FUNCTION        REQUIRED PARAMETERS             DESCRIPTION 
ADDGROUP        [strvalue]                      Creates a new Program Manager  
						group. 
 
ADDITEM         [strvalue1] [strvalue2]         Adds a new item to a Program  
		[pathfile]                      Manager group. 
 
GETINIINT       [pathfile] [strvalue1]          Gets a key value (integer)  
		[strvalue2] [intvar]            from an INI file, and places  
						the result in a variable. 
 
GETINISTR       [pathfile] [strvalue1]          Gets a key value (string)  
		[strvalue2] [strvar]            from an INI file, and places  
						the result in a variable. 
 
SCHEDULEWIN     [path] [filename] [text]        Schedules a file to be run  
						the next time the user runs  
						Windows. 
 
WRITEINIINT     [pathfile] [strvalue1]          Writes a key value (integer)  
		[strvalue2] [intvalue]          to an INI file  
		 
WRITEINISTR     [pathfile] [strvalue1]          Writes a key value (string)  
		[strvalue2] [strvalue3]         to an INI file. 
 
 
Miscellaneous Functions (section 22.7): 
 
FUNCTION        REQUIRED PARAMETERS             DESCRIPTION 
APPENDPATH      [strvar] [strvalue]             Appends the contents of a  
						string value to the end of a  
						string variable; however, it  
						first checks if the last  
						character of a string  
						variable is a "\".  If it  
						is not, APPENDPATH will  
						append a "\" and a value to  
						the variable. 
 
ASSIGN          [intvar] [intvalue]             Performs a basic integer  
						assignment operation. 
 
DEFINE          [text] [defineopt]              Used to create user defined  
						variables of a string or  
						integer type. 
 
EXIT            [intvalue]                      Ends the script. 
 
IF..THEN..ELSE  [intvalue1] [condoper]          Allows conditional processing  
		[intvalue2]                     of functions. 
 
NUMTOSTR        [strvar] [intvalue]             Converts a numeric value to  
						a string variable. 
 
PAUSE           [text]                          Pauses execution of the  
						script until the user presses  
						a key. 
 
REBOOT                                          Immediately reboots the  
						user's PC. 
 
SHELL           [pathfile] {text}{shellopt}     Allows a user to execute an  
						external DOS batch file or  
						executable program. 
 
STRCAT          [strvar] [strvalue]             Appends the contents of a  
						string value to the end of a  
						string variable. 
 
STRCOMPARE      [strvar] [strvalue]             Does a byte for byte  
						comparison of two strings. 
 
STRCOPY         [strvar] [strvalue]             Copies a value into a string,  
						overwriting the previous  
						contents of the string. 
 
WRITELN         [strvalue]                      Writes a string value  
						(e.g., write to screen). 
 
 
NOTE:  In the actual script, parameters are separated by a space; do not  
type the brackets. 
 
22.3.2 User-defined Variables 
 
User-defined variables are defined by using the DEFINE command (see  
Miscellaneous Functions) to create a string or integer user-defined  
variable name.   
 
User-defined variables must be defined before listing any script functions.   
Also, the appropriate type must be used when calling a function that allows  
user-defined variable names.  The functions that allow user-defined  
variables, system variables and literal text use the phrases [strvar]  
or [intvar] in their parameter listings.  Check the Rules discussion in 
section 22.7 entitled "Rules and System Variables" for further details. 
 
 
22.4 DOS Functions 
 
The DOS function set is used for managing a machine's files and directories.   
For example, files can be searched for, copied, deleted, renamed and  
tagged with a specified attribute; directories can be created and deleted. 
 
Return values are generated when appropriate (unless otherwise noted, the  
functions return 0 if successful).  Any applicable system variables are  
also noted.   
 
Most DOS functions return a DOS error code if unsuccessful.  Refer to the  
table in section 22.8 entitled "DOS Error Codes" for a list of the DOS error  
codes that may be returned. 
 
NOTES: a - When an "explicit <path>" is mentioned, it can take the form  
of D:\PATH  (SERVER/VOLUME:\PATH is not currently supported). 
b -  Some functions take optional "options."  The administrator should 
decide whether or not to specify these options. 
c - In the following function specifications, parameters in quotes  
represent literal parameters; all other parameters represent rules.   
The rules are listed in section 22.7 entitled "Rules and System Variables." 
 
ATTRIB [path] [filewild] [attribute] 
 
Parameter       Description and Notes 
[path]          Source path to files. This path must exist. 
 
[filewild]      The file name whose attributes are to be changed. May  
		contain wildcards (? and *). 
 
[attribute]     RO -  Read only   
		RW - Read/Write 
		A -    Set Archive bit 
		SY -   System file 
		H -    Hidden file 
		SH -  Shareable (network <path> only) 
		-A -   Turn off archive attribute 
		-SY - Turn off system attribute 
		-H -   Turn off hidden attribute 
		-SH - Turn off shareable attribute (network <path> only) 
 
 
Description - Changes the attributes of a file or multiple files. 
 
Tip - To remove the Read Only attribute, use the RW attribute.   
(There is no -RO attribute.) 
 
Return Values: 
 
[RETVAL] = 0 if successful 
 
[RETVAL] = -1 if the SH or -SH attributes are used and the drive letter  
specified in [PATH] is not a network drive 
 
[RETVAL] = -2 if the SH or -SH attributes are used and no drive letter is  
specified in [PATH] 
 
[RETVAL] = DOS error code in all other cases 
 
Example -  Set the AUTOEXEC.BAT file on a user's boot drive to Read Only: 
 
	ATTRIB [BOOT_ROOT] "AUTOEXEC.BAT" RO 
 
 
COPY [path] [filewild] [path] {filewild} 
 
Parameter       Description and Notes 
[path]          Source path of file to be copied. 
 
[filewild]      Source file name to be copied. 
		May contain standard DOS wild cards (? and *). 
 
[path]          Destination path. 
 
{filewild}      Optional destination file name.  (If not specified, *.*  
		is assumed.) 
		May contain standard DOS wild cards (? and *). May be used  
		to rename file(s) during file copy.  If not used,  
		the placeholder "" or NULL must be specified. 
 
 
Description - Copies a file or files to another directory and file name(s). 
 
Return Values: 
 
[RETVAL] = 0 if file(s) are copied correctly 
[RETVAL] = DOS error code if the function is unsuccessful 
 
Example - Copy the WIN.INI file from the Windows directory found at login  
to the local Windows directory.  Two examples of this are: 
 
COPY [WINDIR] "WIN.INI" "C:\WINDOWS" ""  
 
				 or 
 
COPY [WINDIR] "WIN.INI" "C:\WINDOWS" NULL 
 
 
DELETEDIR [path] [filename] {deleteopt} 
 
Parameter       Description and Notes 
[path]          Source path to the directory to be deleted. This path  
		must exist. 
 
[filename]      Directory name to be deleted. 
 
{deleteopt}     Optional delete option: ALL - causes DELETEDIR to delete  
		the specified directory and everything under it, including  
		any subdirectories, hidden, system and read only files. If  
		not used, NULL must be specified. 
 
 
Description - Deletes a directory. 
 
Tip - Use the ALL delete option with caution since it can delete entire  
directory trees. 
 
Return Values: 
 
[RETVAL] = 0 if the directory is successfully deleted 
[RETVAL] = DOS error code if the function is unsuccessful 
 
Example - Delete the Windows directory found at login and all of its files  
and sub-directories: 
 
	DELETEDIR [WINDIR] ALL 
 
 
 
DELETEFILE [path] [filewild] 
 
Parameter       Description and Notes 
[path]          Source path to the file(s) to be deleted. This path  
		must exist. 
 
[filewild]      File name(s) to be deleted.  Wild cards may be  
		specified (? and *) to delete multiple files. 
 
		 
Description - Deletes a file or multiple files. 
 
Return Values: 
 
[RETVAL] = 0 if the file(s) are deleted 
[RETVAL] = DOS error code if the function is unsuccessful 
 
Example - Delete all .DOC files from the F:\UZR\JOHN sub-directory: 
 
	DELETEFILE "F:\UZR\JOHN" "*.DOC" 
 
 
 
FINDFILE [path] [filewild] [strvar] 
 
Parameter       Description and Notes 
[path]          Source path in which to search for files.  This path  
		must exist. 
 
[filewild]      The search criteria. May contain wildcards (? and *). 
 
[strvar]        A string variable which contains the file name of the  
		first file found.  (Before being used as a parameter,  
		this variable must be defined using the DEFINE function.) 
 
 
Description - Finds a file. 
 
Return Values: 
 
[RETVAL] = 0 and copies the name of the first file found into [STRVAL]  
if successful 
[RETVAL] = -1 and sets [STRVAL] to NULL if no files are found 
 
Example -  Test for the presence of the NET.CFG file in the [NET.CFG]  
directory: 
 
	DEFINE "Result" STRING 
	FINDFILE [NETCFG] "NET.CFG" RESULT 
 
 
MDIR [path] [filename] 
 
Parameter       Description and Notes 
[path]          Path in which to create the new directory. This path  
		must exist. 
 
[filename]      Sub-directory to create. Wild cards may not be specified. 
 
 
Description - Creates a directory. 
 
Return Values: 
 
[RETVAL] = 0 if the directory is successfully created 
[RETVAL] = DOS error code if the function is unsuccessful 
 
Example - Create the JOHN sub-directory in the UZR directory: 
 
	MDIR "F:\UZR" "JOHN" 
 
 
 
RENAME [path] [filewild] [path] [filewild] 
 
Parameter       Description and Notes 
[path]          Source path to files to be renamed. This path must exist. 
 
[filewild]      Source file name to be renamed. May contain wildcards  
		(? and *). 
 
[path]          Destination path (can be different than [path] to enable  
		moving files, but the drives must be the same). 
 
[filewild]      New file name.  May contain wildcards (? and *).   
		If so, the standards used by the DOS REN command are followed. 
 
 
Description - Renames a source file(s). 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code in all other cases 
 
Example -  Rename all .BAT files in the C:\ drive to .BAK: 
 
	RENAME "C:\" "*.BAT" "C:\" "*.BAK" 
 
 
 
UPGRADEOS [upgopt] 
 
Parameter       Description and Notes 
[upgopt]        5.00 - upgrade DOS version to 5.00 
		6.00 - upgrade DOS version to 6.00 
 
 
Description - Upgrades DOS version from 3.x-5x to either 5.00 or 6.00. 
 
Tips: 
1) In order for BrightWorks to have access to the upgraded DOS files,  
EQUIP must first be run on a machine that has the desired DOS files.   
For example, to upgrade a machine's DOS version to 6.00, EQUIP first must  
be executed on a machine that has DOS 6.00.  By executing EQUIP from the  
same directory in which the BrightWorks software distribution update  
program (SDUPDATE.EXE) file is located, the DOS files become accessible  
by BrightWorks.  Note also that the machine on which EQUIP is run must  
not contain any system that modifies the machine's boot record  
(e.g., OS/2, Windows NT). 
 
NOTE:  Do not use this function on a workstation that has Windows NT  
installed in a dual boot configuration.  It will cause the boot menu to be  
lost.  The PC will boot DOS only. 
 
2) The machine must be rebooted after the script is executed.  Use the  
REBOOT function as the last script function. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code in all other cases 
 
Example -  Upgrade a user's DOS version to 5.00: 
 
	UPGRADEOS 5.00 
	IF [RETVAL]=0 
		... 
		; copy DOS files, edit CONFIG.SYS, etc. 
		REBOOT 
	ENDIF 
 
 
 
22.5 Easy System File Functions 
 
The Easy System File functions allow for easy manipulation of basic  
system files, such as CONFIG.SYS, AUTOEXEC.BAT, NET.CFG, or a login script.   
(Use the Windows System File functions to edit .INI files.) 
 
Most Easy System File functions return a DOS error code if unsuccessful.   
Refer to the table in section 22.8 entitled "DOS Error Codes" for a list of  
the DOS error codes that may be returned. 
 
NOTE:  Prior to using any of the functions in this category, you must call  
SETSYSFILE.  Also, none of the functions will create a backup of the file  
that they are modifying; however, a file will not be modified if a function  
fails.  It is your responsibility to backup any file as necessary. 
 
All of the Easy System File functions make use of a "key" value.  This  
value is used to search the file to aid in determining where to make a  
modification.  All key searches are case insensitive.  If a key is found,  
its corresponding value is defined as the first non- whitespace (e.g. tab,  
cr/lf, =, etc.) group of characters after the found key value.   
For example, consider the following line: 
 
	PATH=C:\DOS;C:\WINDOWS 
 
If "PATH" is specified as the key, then the corresponding value is  
"C:\DOS;C:\WINDOWS."  However, consider the following line: 
 
	STACKS 9,256 
 
If "STACKS" is specified as the key, then the corresponding value is "9,256."   
As a result, an equal sign is not necessary to identify a value that  
you might want to edit. 
 
NOTE:  In the following function specifications, parameters in quotes  
represent literal parameters; all other parameters represent rules.  The  
rules are listed later in this chapter. 
 
 
ADDDEVICE [strvalue1] [strvalue2] [addopt] 
 
Parameter       Description and Notes 
[strvalue1]     The path and driver name (e.g. C:\WINDOWS\EMM386.EXE). 
 
[strvalue2]     The key value to search for (e.g. HIMEM.SYS). 
 
[addopt]        Where [strvalue1] is to be placed: either BEFORE or AFTER  
		[strvalue2]. 
 
 
Description - Adds a new DEVICE= line to a system file (typically the  
DOS CONFIG.SYS). 
 
Tip - If [strvalue2] is a null string or the key is not found, ADDDEVICE  
will add [strvalue1] in the position of the file indicated by [addopt]. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code in all other cases 
 
Example - Place "DEVICE=C:\WINDOWS\EMM386.EXE" after the "DEVICE=HIMEM.SYS"  
line in the CONFIG.SYS file: 
 
	SETSYSFILE "C:\" "CONFIG.SYS" 
	ADDDEVICE "C:\WINDOWS\EMM386.EXE" "HIMEM.SYS" AFTER 
	 
 
ADDLINE [strvalue1] [strvalue2] [addopt] 
 
Parameter       Description and Notes 
[strvalue1]     The entire line of text you wish to add. 
 
[strvalue2]     A reference key value to be positioned relative to  
		[strvalue1].  This is a "keyword" that will be searched  
		for in the file.  Specify as much or as little as you like.   
		When the first occurrence of the keyword in a line is found,  
		that line is used as the reference. 
 
[addopt]        Specify where [strvalue1] is to be placed: either BEFORE or  
		AFTER [strvalue2]. 
 
 
Description - Adds a line of text to a system file. 
 
Tip - If [strvalue2] is a null string, ADDLINE will place [strvalue1] in  
the position of the file indicated by [addopt]. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code in all other cases 
 
Example -  Add a new line to the end of a user's CONFIG.SYS file: 
 
	SETSYSFILE "C:\" "CONFIG.SYS" 
	ADDLINE "THIS IS NEW.." "" AFTER 
 
NOTE:  As in the example above, non-specified parameters  
(e.g., [strvalue2]) can be indicated by empty quotes.  Entering NULL  
with no quotes is also acceptable. 
 
 
 
ADDPATH [strvalue1] [strvalue2] [strvalue3] [addopt] 
 
Parameter       Description and Notes 
[strvalue1]     The name of the path environment variable to edit (PATH for  
		DOS, or DPATH for OS/2, or TEMP, etc). 
 
[strvalue2]     The sub-directory to be added. 
 
[strvalue3]     The sub-directory that [strvalue2] will be placed either  
		before or after. 
 
[addopt]        Specify where [strvalue2] is to be placed: either BEFORE  
		or AFTER [strvalue3]. 
 
 
Description - Adds a sub-directory to a path environment variable. 
 
Tips: 
 
1) If [strvalue3] is a null string, ADDPATH will place [strvalue2] in the  
position of the path statement indicated by [addopt] (i.e., the new path  
will be placed at the beginning or end of the path statement).  
 
2) If the key specified in [strvalue1] is not found, then a new one is  
added, with a "SET" prepended.  This allows for adding path like environment  
variables such as "SET TEMP=", and so on.  
 
3) This function can also be used to edit other lines such as a TEMP  
environment variable, or any other line that does something like  
"SET envvar=d:\path." 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code in all other cases 
 
Example -  Add the sub-directory WINDOWS to the path and place it before  
the DOS variable in the AUTOEXEC.BAT file: 
 
	SETSYSFILE "C:\" "AUTOEXEC.BAT" 
	ADDPATH "PATH" "C:\WINDOWS" "C:\DOS" BEFORE 
 
 
 
CFGGETVALUE [strvalue] [intvar] 
 
Parameter       Description and Notes 
[strvalue]      The variable to be retrieved. 
 
[intvar]        An integer variable to hold the retrieved value.   
		(Before being used as a parameter, this variable must  
		be defined using the DEFINE function.) 
 
 
Description - Gets a numeric variable from a system file (e.g., FILES,  
BUFFERS, etc.). 
 
Tip - If the value of the key specified is non-numeric (e.g., the DOS=HIGH),  
CFGGETVALUE sets parameter 2 to 0, but does not return an error code.   
Use CFGGETSTRING to get a string value. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = -2 if the key value could not be found 
[RETVAL] = DOS error code in all other cases 
 
Example - Place the value of the FILES= statement in the CONFIG.SYS file  
into a user defined variable called nRESULT (which must first be defined!): 
 
	DEFINE "nRESULT" STRING 
	SETSYSFILE "C:\" "CONFIG.SYS" 
	CFGGETVALUE "FILES" nRESULT 
 
 
 
CFGSETVALUE [strvalue] [intvalue] 
 
Parameter       Description and Notes 
[strvalue]      The variable to be set. 
 
[intvalue]      The integer value. 
 
 
Description - Sets a numeric variable in a system file (e.g., FILES,  
BUFFERS, etc.). 
 
Tip: Use ADDLINE to add a new statement if one does not exist. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = -2 if the key value could not be found 
[RETVAL] = DOS error code in all other cases 
 
Example - Set the value of the FILES= statement in the CONFIG.SYS file to 50,  
provided a FILES= statement already exists in the file: 
 
	SETSYSFILE "C:\" "CONFIG.SYS" 
	CFGSETVALUE "FILES" 50 
	CFGGETSTRING [strvalue] [strvar] 
	CFGSETSTRING [strvalue1] [strvalue2] 
 
These two functions act exactly the same as CFG???VALUE, except they deal  
with string values rather than integer values.  An administrator might use  
this to check non-numeric variables (e.g., STACKS=9,256 is a non numeric  
value). 
 
Note that before using the [strvar] variable as a parameter, the variable  
must be defined using the DEFINE function. 
 
 
 
REPLACEKEY [strvalue1] [strvalue2] [strvalue3] 
 
Parameter       Description and Notes 
[strvalue1]     The line in the system file which contains the key value  
		to be replaced. 
 
[strvalue2]     The key value to be replaced. 
 
[strvalue3]     The new value. 
 
 
Description - Similar to REPLACELINE; however, it replaces a key value  
rather than the entire line. 
 
Tip - If [strvalue3] is a null string, [strvalue2] will be removed. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code in all other cases 
 
Example -  Change the "40" to a "50" in the FILES= line in the CONFIG.SYS  
file: 
 
	SETSYSFILE "C:\" "CONFIG.SYS" 
	REPLACEKEY "FILES=40" "40" "50" 
 
 
 
REPLACELINE [strvalue1] [strvalue2] 
 
Parameter       Description and Notes 
[strvalue1]     The key value of the line you wish to replace, such as PATH,  
		COMSPEC or DEVICE. 
 
[strvalue2]     The new value of the entire line. 
 
 
Description - Replaces an existing line in a system file with a new line. 
 
Tips: 
 
1) If [strvalue2] is a null string, then the line will be deleted. 
 
2) If the key value exists more than one time in the file, only the first  
instance is modified.  
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code in all other cases 
 
Example - Replace the existing COMSPEC line in the CONFIG.SYS file with a  
new line: 
 
	SETSYSFILE "C:\" "CONFIG.SYS" 
	REPLACELINE "COMSPEC" "SET COMSPEC=C:\DRDOS\COMMAND.COM" 
	 
 
REPLACELINEADD [strvalue1] [strvalue2] [addopt] 
 
Parameter       Description and Notes 
[strvalue1]     The key value of the line you wish to replace, such as PATH,  
		COMSPEC or DEVICE. 
 
[strvalue2]     The new value of the entire line. 
 
[addopt]        Where [strvalue1] is to be placed: either BEFORE or AFTER  
		[strvalue2]. 
 
 
Description - Similar to REPLACELINE, this function replaces an existing  
line in a system file with a new line.  However, if the key specified in  
[strvalue1] is not found, then the line specified in [strvalue2] is added  
to the file, at the beginning or end of the file depending on the position  
defined by [addopt]. 
 
Tip: If [strvalue1] is not found, then the line specified as [strvalue2]  
will be added to the file in the position defined by [addopt]. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code in all other cases 
 
Example - Replace the existing NETX line with the new line C:\NET\VLM.   
If NETX is not found, then the line will be appended to the end of the file: 
 
	SETSYSFILE "C:\" "NET.BAT" 
	REPLACELINEADD "NETX" "C:\NET\VLM" AFTER 
 
 
 
SETSYSFILE [path] [filename] 
 
Parameter       Description and Notes 
[path]          The path to the file to be modified.  
 
[filename]      The name of the file to be modified. 
 
 
Description - Sets a system file to be manipulated. 
 
Tips: 
 
1) This function must be called prior to calling any of the functions in  
the Easy System File function category.  It needs to be called only once,  
unless you change the file you are working on in the script. 
 
2) Using [BOOT_ROOT] as the [path] parameter will always modify the file on  
the boot disk, regardless of whether or not the user is given the option to  
override the installation path (in the package definition).  Use [TARGET]  
as the [path] parameter if the user is given the option to override the  
installation path. 
 
Return Values: 
 
[RETVAL] = 0 if file is found 
[RETVAL] = 2 if file is not found 
 
Example -  Designate a user's CONFIG.SYS file as the file to be edited.   
Two examples of this are: 
 
	SETSYSFILE "C:\" "CONFIG.SYS" 
	or 
	SETSYSFILE [BOOT_ROOT] "CONFIG.SYS" 
 
 
22.6 Windows System File Functions 
 
The Windows System File functions provide the ability to edit INI files  
and create and manipulate Program Manager groups. 
 
NOTES:  a - In the following function specifications, parameters in  
quotes represent literal parameters; all other parameters represent rules.   
The rules are listed in section 22.8 entitled "DOS Error Codes." 
b - Many of the Windows System File functions have a [pathfile] parameter  
which specifies the path name and file name to an INI file.  If you do  
not specify a full path to the Windows directory, then the actions  
performed by these functions occur on the first instance of Windows found,  
as determined by the path statement of the receiving machine.  If Windows  
is not found in the path, then the distribution update program will search  
for the INI file in [BOOT_ROOT]\WINDOWS.  If Windows is still not found,  
the update program will then try [BOOT_ROOT]\WIN31. 
c - The functions ADDGROUP, ADDITEM, and SCHEDULEWIN use the WSDUPD.EXE  
update program which is copied into the local Windows directory each  
time these functions are used.  The next time the user runs Windows,  
WSDUPD.EXE runs and executes the appropriate function(s).  It then deletes  
WSDUPD.EXE and WSDUPD.INI.  If a user has SHARE.EXE loaded, a  
"sharing violation" message will display when trying to delete WSDUPD.EXE.   
This message can be ignored. 
 
 
ADDGROUP [strvalue]   
 
Parameter       Description and Notes 
[strvalue]      The string which specifies the name of the Program Manager  
		group to be added. 
 
 
Description - Creates a new Program Manager group. 
 
Tip: When the ADDGROUP script function is executed, the BrightWorks  
software distribution update program WSDUPD.EXE is automatically copied  
into the workstation's Windows directory.  The WSDUPD.EXE command is also  
added to the "Load=" line in the WIN.INI file.  The next time Windows is  
run at the workstation, the function is executed and WSDUPD.EXE is removed  
from the WIN.INI "Load=" line. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code if unsuccessful.  The function might fail if  
WSDUPD.EXE could not be copied into the Windows directory or if the  
WSDUPD.EXE control file (WSDUPD.INI) could not be created. 
 
Example -  Create a Program Manager group named COMPANY: 
 
	ADDGROUP "COMPANY" 
 
NOTE:  This function can be used with any third party shell program which  
emulates the Program Manager DDE interface. 
 
 
 
ADDITEM [strvalue1] [strvalue2] [pathfile]  
 
Parameter       Description and Notes 
[strvalue1]     The group to which the item will be added. 
 
[strvalue2]     The name of the new item. 
 
[pathfile]      The .EXE file to be associated with the new item. 
 
 
Description - Adds a new item to a Program Manager group. 
 
Tip: When the ADDITEM script function is executed, the BrightWorks  
software distribution update program WSDUPD.EXE is automatically copied  
into the workstation's Windows directory.  The WSDUPD.EXE command is  
also added to the "Load=" line in the WIN.INI file.  The next time  
Windows is run at the workstation, the function is executed and WSDUPD.EXE  
is removed from the WIN.INI "Load=" line. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code if unsuccessful.  The function might fail if  
WSDUPD.EXE could not be copied into the Windows directory or if the  
WSDUPD.EXE control file (WSDUPD.INI) could not be created. 
 
Example -  Create a Program Manager group named APPS, and then create a  
program icon within the new APPS group named EXCEL: 
 
	ADDGROUP "APPS" 
	ADDITEM "APPS" "EXCEL" "U:\MS\EXCEL\EXCEL.EXE" 
 
NOTE:  This function can be used with any third party shell program which  
emulates the Program Manager DDE interface. 
Also note that the path specified will appear in the command line as well as 
the working directory. The above EXCEL example demonstrates this. 
 
 
 
GETINIINT [pathfile] [strvalue1] [strvalue2] [intvar] 
 
This function works in exactly the same way as GETINISTR (below) except  
it is used to retrieve integer values from INI files. 
 
 
 
GETINISTR [pathfile] [strvalue1] [strvalue2] [strvar] 
 
Parameter       Description and Notes 
[pathfile]      The path and file name of the INI file. 
 
[strvalue1]     The section of the INI file in which the entry is located  
		(e.g., [386Enh]). 
 
[strvalue2]     The entry whose associated string is to be retrieved  
		(e.g., keyboard.drv=, however, do not include the = sign!). 
 
[strvar]        Variable in which to place the found string.  (Before being  
		used as a parameter, this variable must be defined using  
		the DEFINE function.) 
 
 
Description - Gets a key value (string) from an INI file, and places the  
result in a variable. 
 
Tip - If [strvalue2] is a null string or the key is not found, ADDDEVICE  
will add [strvalue1] in the position of the file indicated by [addopt]. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = -1 if the [strvalue2]  section name does not exist 
[RETVAL] = -2 if the [strvalue3]  key does not exist 
[RETVAL] = DOS error code in all other cases 
 
Example -  Determine whether Windows version 3.1 is installed at a  
workstation by looking at the CONTROL.INI file:  
 
	DEFINE "VER" STRING 
	GETINISTR "C:\WIN\CONTROL.INI" "[INSTALLED]" "3.1" VER 
 
 
 
SCHEDULEWIN [path] [filename] [text] 
 
Parameter       Description and Notes 
[path]          The path to the file to be run. 
 
[filename]      The file name to be run upon Windows execution. 
 
[text]          Optional command line arguments for the file. 
 
 
Description - Schedules a file to be run the next time the user runs Windows. 
 
Tip - This function could be used to automate the installation of a  
Windows program if a macro playback utility is used. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code if unsuccessful.  The function might fail if  
WSDUPD.EXE could not be copied into the Windows directory or if the  
WSDUPD.EXE control file (WSDUPD.INI) could not be created. 
 
Example -  Schedule the Notepad program to run the next time Windows is run,  
and also open the README.TXT notepad file: 
 
	SCHEDULEWIN "C:\WINDOWS" "NOTEPAD.EXE" "README.TXT" 
	 
	 
WRITEINIINT [pathfile] [strvalue1] [strvalue2] [intvalue] 
 
This function works exactly like WRITEINISTR (below), except that it is  
used to write an integer value to an INI file. 
 
 
WRITEINISTR [pathfile] [strvalue1] [strvalue2] [strvalue3] 
 
Parameter       Description and Notes 
[pathfile]      The path and file name of the INI file. 
 
[strvalue1]     The section in which [strvalue2] is located (e.g., [386Enh]). 
 
[strvalue2]     The entry whose associated string is to be modified  
		(e.g., keyboard.drv=, however, don't include the = sign!). 
 
[strvalue3]     The string to be written to the INI file. 
 
 
Description - Gets a key value (string) from an INI file, and writes the  
result to the INI file. 
 
Tips: 
 
1) If the section name specified in [strvalue1] is not found, then it will  
be added to the end of the INI file, with a new key=value added in that  
section. 
 
2) If the [strvalue1] section is found but the key value specified in  
[strvalue2] is not found, the new key value is added directly after the  
section name [strvalue1]. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = DOS error code in all other cases 
 
Example -  Define a "medium priority" in the [SPOOLER] section of the  
WIN.INI file:  
 
	WRITEINISTR "C:\WIN\WIN.INI" "[SPOOLER]" "PRIORITY" "MEDIUM" 
 
 
 
22.7 Miscellaneous Functions 
 
The Miscellaneous Functions include basic functions for defining, assigning,  
copying, comparing and concatenating variables. 
 
NOTE:  In the following function specifications, parameters in quotes  
represent literal parameters; all other parameters represent rules.   
The rules are listed in section 22.8 entitled "DOS Error Codes."  
 
 
APPENDPATH [strvar] [strvalue] 
 
Parameter       Description and Notes 
[strvar]        The variable to contain the appended string  
		(i.e., destination).  (Before being used as a parameter,  
		this variable must be defined using the DEFINE function.) 
 
[strvalue]      The string value to be appended (i.e., source). 
 
 
Description - Adds a file name to a path or builds a path.  This function  
acts the same way as STRCAT, except that it will check if the last  
character of [strvar] is a "\".  If it is not, APPENDPATH will append  
a "\" to [strvar], and then [strvalue] will be appended.  This is very  
useful (and necessary!) in building paths. 
 
Return Value: 
 
[RETVAL] = 0 always 
 
Example - Define the variable named PATH to be a string-type.  Copy the  
location of the network configuration files into the PATH variable and  
then append it to the C:\DRIVERS directory. 
 
	DEFINE "PATH" STRING 
	STRCOPY PATH [NETCFG] 
	APPENDPATH "C:\DRIVERS" PATH 
 
 
 
ASSIGN [intvar] [intvalue] 
 
Parameter       Description and Notes 
[intvar]        The integer type variable name which will be assigned a  
		value.  (Before being used as a parameter, this variable  
		must be defined using the DEFINE function.) 
		 
[intvalue]      The numeric value to be assigned to the integer type variable. 
 
 
Description - Performs a basic integer assignment operation (e.g., a = b). 
 
Return Value: 
 
[RETVAL] = 0 always 
 
Example -  Define the variable "NUM" as an integer type, and later assign  
33 to the variable NUM:  
 
	DEFINE "NUM" INTEGER 
	ASSIGN NUM 33 
 
 
 
DEFINE [text] [defineopt] 
 
Parameter       Description and Notes 
[text]          The variable being defined. 
 
[defineopt]     The type of variable being defined (e.g., STRING or INTEGER). 
 
 
Description - Used to create user defined variables of a string or integer  
type.  This variable can then be used later in the script. 
 
Tips: 
1) All DEFINE statements must be declared before any script command  
is executed. 
 
2)  If a STRING type variable is declared, the login module will allocate  
255 bytes (= 255 characters) of memory for the string.  If an INTEGER  
type variable is declared, the login module will allocate 4 bytes (C type  
long which equals to an approximately -2 billion to +2 billion size integer).  
 
Return Value: 
 
[RETVAL] = 0 always 
 
Example -  Define the variable "ANSWER" as a string type. 
 
	DEFINE "ANSWER" STRING 
 
 
 
EXIT [intvalue] 
 
Parameter       Description and Notes 
[intvalue]      An integer type variable. 
 
 
Description - Ends the script. 
 
Tips: 
 
1) If [intvalue] is set to a non-zero value, then the login module will  
increment the error count by one for the upgrade package and note the log  
with the error number returned. 
 
2) If the package has been defined to execute the script before decompressing  
the fileset, then the EXIT command will prevent the decompression of the  
fileset.  (For more information on defining "Advanced Package Options,"  
refer to the section later in this chapter.) 
 
Return Value: none 
 
Example -  End the script if an obtained value is greater than 50: 
 
	IF RESULT <= 50 
		CFGSETVALUE "FILES" 55 
	ELSE 
		EXIT 1 
	ENDIF 
 
 
IF [intvalue1] [condoper] [intvalue2] ... {ELSE...} ENDIF 
 
Parameter       Description and Notes 
[intvalue1]     An integer type variable to be evaluated against [intvalue2]. 
 
[condoper]      Valid conditional operators are: =, !=, <, >, <=, >= 
 
[intvalue2]     An integer type variable to evaluate [intvalue1] against. 
 
Description - Allows conditional processing of functions.  IF..THEN  
evaluates the conditional expression defined by [intvalue1] [condoper]  
[intvalue2].  If the condition evaluates to be TRUE, then all functions  
following THEN are executed until an ELSE or ENDIF is reached.  If the  
condition evaluates to FALSE and ELSE is defined, then all functions  
following the ELSE are executed until an ENDIF is reached.   
 
Tip - IFs can be nested up to 50 levels deep. 
 
Return Value: none 
 
Example -  Obtain the FILES= value from the CONFIG.SYS file.  If the value  
is less than or equal to 50, then change the value to 55; otherwise, exit  
the script: 
 
	DEFINE "RESULT" INTEGER 
	SETSYSFILE "C:\" "CONFIG.SYS" 
	CFGGETVALUE "FILES" RESULT 
	IF RESULT <= 50 
		CFGSETVALUE "FILES" 55 
	ELSE 
		EXIT 1 
	ENDIF 
 
 
NUMTOSTR [strvar] [intvalue] 
 
Parameter       Description and Notes 
[strvar]        The variable to contain the converted value.  (Before being  
		used as a parameter, this variable must be defined using  
		the DEFINE function.) 
 
[intvalue]      The numeric value to be converted. 
 
 
Description - Converts a numeric value to a string variable. 
 
Return Value: 
 
[RETVAL] = 0 always 
 
Example -  Convert the number 100 to a string and store the value in the  
defined variable named ONEHUNDRED: 
 
	DEFINE "ONEHUNDRED" STRING 
	NUMTOSTR ONEHUNDRED 100 
 
 
PAUSE [text] 
 
Parameter       Description and Notes 
[text]          The text to be displayed on the user's screen during the  
		pause. (This can be NULL) 
 
 
Description - Pauses execution of the script until the user presses a key. 
 
Tip - If [text]1 is NULL, then the default message "Strike any key to  
continue" is displayed on the screen. 
 
Return Value = 0 always 
 
Example -  Display the message "Pausing... press any key to continue"  
during script execution. 
 
	PAUSE "PAUSING ... PRESS ANY KEY TO CONTINUE." 
 
 
 
REBOOT 
 
This function immediately reboots the user's PC.  It does not accept any  
parameters and does not return any values.  Before the reboot, the script  
file is closed, the log database is closed, and any necessary cleanup is  
performed. 
 
NOTES: a - The PC will not reboot if a fileset is to be executed after the  
script. 
b -  The REBOOT function might not work if the workstation is not 100% PC  
compatible. 
 
 
SHELL [pathfile] {text} {shellopt} 
 
Parameter       Description and Notes 
[pathfile]      The path and file name to execute. 
{text}          The file's optional command line arguments.  (This can be  
		NULL.) 
 
{shellopt}      Optional argument which can only be either [KEEPPATH] or NULL. 
 
 
Description - Allows a user to execute an external DOS batch file,  
executable program, or DOS command. 
 
Tip - To execute the program or batch file in [pathfile] and change to the  
specified path, use the KEEPPATH option as the {shellopt} parameter.  If  
you don't specify the KEEPPATH option, SHELL will try to use the path from  
which the SDUPDATE program was run.  KEEPPATH allows you to temporarily  
switch to the path from where you want to run the program. 
 
Return Values: 
 
[RETVAL] = 0 if successful 
[RETVAL] = -1 if failed 
 
Example -  Execute LIST.COM and load the contents of the README.TXT file.  
Temporarily make the current directory C:\PUB\LIST.COM. 
 
	SHELL "C:\PUB\LIST.COM" "README.TXT" "" KEEPPATH 
 
 
STRCAT [strvar] [strvalue] 
 
Parameter       Description and Notes 
[strvar]        The variable to contain the concatenated string  
		(i.e., destination).  (Before being used as a parameter,  
		this variable must be defined using the DEFINE function.) 
 
[strvalue]      The string value to be appended (i.e., source). 
 
 
Description - Appends the contents of [strvalue] to the end of the string  
[strvar]. 
 
Tip - If the resulting text in [strvar] is longer than the space allowed  
(255 bytes), then it will be truncated and properly null terminated. 
 
Return Value: 
 
[RETVAL] = 0 always 
 
Example -  Add the string "ADDTHIS" to a string variable named STRINGS1&2: 
 
	DEFINE "STRINGS1&2" STRING 
	STRCAT STRINGS1&2 "ADDTHIS" 
 
 
STRCOMPARE [strvar] [strvalue] 
 
Parameter       Description and Notes 
[strvar]        The variable to be compared.  (Before being used as a  
		parameter, this variable must be defined using the  
		DEFINE function.) 
 
[strvalue]      The value to compare the variable against.  
 
 
Description - Does a byte for byte comparison of two strings. 
 
Return Values: 
 
[RETVAL] = 0 if the strings are identical 
[RETVAL] = < 0 if [strvar] is less than [strvalue] 
[RETVAL] =  > 0 if [strvar] is greater than [strvalue] 
 
Example -  Check the current NetWare login name against a specified login  
name ("Supervisor"). 
 
	DEFINE "NAME" STRING 
	STRCOPY NAME [LOGINNAME] 
	STRCOMPARE NAME "SUPERVISOR" 
 
 
STRCOPY [strvar] [strvalue] 
 
Parameter       Description and Notes 
[strvar]        The variable to receive the copied string value  
		(i.e., destination).  (Before being used as a parameter,  
		this variable must be defined using the DEFINE function.) 
 
[strvalue]      The string value to be copied (i.e., source). 
 
 
Description - Copies a value into a string, overwriting the previous  
contents of the string. 
 
Return Value: 
 
[RETVAL] = 0 always 
 
Example -  Copy the string "ABC" into the string variable named "HOLDABC": 
 
	DEFINE "HOLDABC" STRING 
	STRCOPY HOLDABC "ABC" 
 
 
WRITELN [strvalue] 
 
Parameter       Description and Notes 
[strvalue]      The string to display on screen. 
 
 
Description - Writes the [strvalue] line to stdout (e.g., the screen).   
This might be useful for displaying error messages, etc. 
 
Return Value: 
 
[RETVAL] = 0 always 
 
Example -  Define the variable named RESULT.  Place the value of the  
FILES= statement in the CONFIG.SYS file into RESULT, and then write the  
value of RESULT. 
 
	DEFINE "VALUE" STRING 
	DEFINE "RESULT" INTEGER 
	SETSYSFILE "C:\" "CONFIG.SYS" 
	CFGGETVALUE "FILES" RESULT 
	NUMTOSTR VALUE RESULT 
	WRITELN VALUE 
 
 
 
22.8 Rules and System Variables 
 
Most of the functions in the BrightWorks script language have parameters  
that are specified or passed to them.  The valid entries for each parameter  
type are called rules.  For example, the UPGRADEOS function has one  
parameter named [upgopt].  As indicated in the table below, the value of  
the [upgopt] parameter can be either 5.00 or 6.00.  Therefore, the  
allowable values for the [upgopt] parameter are 5.00 and 6.00. 
 
NOTE:  When a user defined variable of string type is expected, [STRVAR] is  
the rule.  When a user defined variable of integer type is expected,  
[INTVAR] is the rule. 
 
The table below lists the rules (allowable values) for each parameter. 
 
Rule Name       Allowed Values 
ADDOPT          BEFORE AFTER 
ATTRIBUTE       RO  RW  A  SY  H  SH -A -SY -H -SH 
CONDOPER        <  >  =  !=  >=  <= 
DEFINEOPT       STRING  INTEGER 
DELETEOPT       ALL 
FILENAME        [STRVAR] "filename.ext" (wild cards not allowed for file name) 
FILEWILD        [STRVAR] "filename.ext" "*.*" (wild cards are allowed but  
		not required for a file name) 
INTVALUE        [INTVAR] [RETVAL]  # (where # is a valid integer) 
INTVAR          [INTVAR] 
PATH            [STRVAR] "path" [TARGET] [BOOT_ROOT] [WINDIR] [WINSYSDIR]  
		[NETCFG] [HDRIVE] [NDRIVE] [SERVERNAME] [LOGINNAME]  
		[FUSIONNAME] [LOGSCRNAME] 
PATHFILE        [STRVAR] "{path\}filename.ext" 
SHELLOPT        KEEPPATH 
STRVAR          [STRVAR] 
STRVALUE        [STRVAR] "text" [TARGET] [BOOT_ROOT] [WINDIR] [WINSYSDIR]  
		[NETCFG] [HDRIVE] [NDRIVE] [SERVERNAME] [LOGINNAME]  
		[FUSIONNAME] [LOGSCRNAME] 
TEXT            "text" 
UPGOPT          5.00 6.00 
	  
 
22.8.1 System Variables 
 
The rules listed in the above table are defined as follows: 
 
22.8.2 String Type Rules: 
 
[BOOT_ROOT] - the root of the boot drive of the workstation on which the  
script is executed 
 
[HDRIVE] - drive letter of the first available hard drive  (may be boot or  
network drive) 
 
[FUSIONNAME] - primary user name from BrightWorks databases (generally same  
as LOGINNAME) 
 
[LOCATION] - location field from BrightWorks inventory databases 
 
[LOGINNAME] - login name of user 
 
[LOGSCRNAME] - full path and file name of login script for user running  
update. 
 
[NDRIVE] - drive letter of the first available network drive 
 
[NETCFG] - path to NET.CFG used at NetWare shell load (must be in path) 
 
[SERVERNAME] - name of server on which the update program is running 
 
[TARGET] - installation path as defined by the administrator (or changed  
by user, if able to) 
 
[WINDIR] - the user's Windows directory (directory in which the login  
module finds WIN.INI - this directory must be in the path) 
 
[WINSYSDIR] - the user's Windows\System directory (directory in which the  
login module finds USER.EXE - this directory may be in the SYSTEM  
directory below WINDIR, or in the path) 
 
22.8.3 Integer Type Rules: 
 
[DISKSPACE] - available disk space in drive specified in [TARGETDIR].   
The number is in bytes. 
 
[RETVAL] - return code of last command completed 
 
 
22.9 DOS Error Codes 
 
The following lists the DOS error codes that may be returned from the  
script functions.  For each error, the number, message, reason, action,  
and functions that return the error are described. 
 
o Message # 2 - "File not found." Reason: file specified in the script  
does not exist. Check the filename and path. Functions returning error: 
GETINISTR() - The file from which you requested a string does not exist.  
GETINIINT() - The file from which you requested an integer does not exist. 
 
o  Message # 3 -  "Path not found." Reason: a directory path specified  
in the script does not exist.  Check the path and directory name.  Functions 
returning error: DELETEDIR() - The directory that you requested to delete  
does not exist, or it does not exist in the location you specified. 
 
o  Message # 4 - "Too many open files (no handles left)." Reason:  
insufficient file handles are specified in CONFIG.SYS.  Increase the  
number of file handles in CONFIG.SYS.  Functions returning error: COPY()  
All Easy System File and Windows System File functions. 
 
o  Message # 5 - "Access denied." Reasons: specified drive or file cannot  
be accessed. Insufficient user rights, read only files, disk full. Verify  
the user rights, file attributes and available disk space. Functions  
returning error: DELETEFILE(), ADDPATH(), ADDLINE(), REPLACELINE(),  
REPLACEKEY(), ADDDEVICE(), CFGSETVALUE(), CFGSETSTRING(), REPLACELINEADD(),  
WRITEINISTR(), WRITEINIINT() - Is the file flagged read only?  Is the  
disk full?  Does the end user have insufficient rights in the specified  
directory?  DELETEDIR() - Subdirectories and/or files exist, and the  
"ALL" option was not used in the script.  ADDGROUP(), ADDITEM(),  
SCHEDULEWIN() - Is WIN.INI flagged read only?  
 
o  Message # 8 - "Insufficient memory" Reason: Not enough memory to  
complete the specified action. Unload unnecessary TSRs, check workstation  
memory management.  Functions returning this error: All DOS, Easy System  
File and Windows System File functions. 
 
o  Message # 15 - "Invalid drive" Reason: The drive specified does not  
exist. Check the drives specified in the script. Functions returning this       
error: All DOS, Easy System File and Windows System File functions. 
 
o  Message # 16 - "Attempt to remove current directory" Reason: The  
directory you attempted to delete is active on a drive.  Functions returning               
this error: DELETEDIR() - Is the directory specified active on the drive?   
If it is a network drive, are other users active on the drive?  
 
o  Message # 17 - "Not same device" Reason: An action was specified on  
two separate drives.  Ensure that you are not attempting to "cross drives"  
on an action that does not permit this (e.g., RENAME)  Functions returning   
this error: RENAME() - Are the source and target locations different? 
 
o  Message # 18 - "No more files"  Reason: The specified file could not be  
found.  Check the path and filename. Check end user rights in the directory  
specified.  Functions returning this error: DELFILE(), ATTRIB(), RENAME(),  
SETSYSFILE(),  COPY() - Does the specified file exist in the location  
specified?  Does the end user have sufficient rights to see the file? 
 
o  Message # 19 - "Disk is write protected"  Reason:  The write protect  
tab is enabled on the disk specified in the operation.  Remove the write  
protect tab.  Functions returning this error:  All DOS, Easy System File  
and Windows System File functions. 
 
o  Message # 21 - "Drive not ready"  Reason: There is no disk in the drive  
specified in the operation. Insert the diskette.  Functions returning this   
error: All DOS, Easy System File and Windows System File functions. 
 
o  Message # 22 - "Invalid disk command"  Reason: Media access error.      
Check the diskette or drive. Functions returning this error: Bad or  
damaged diskette. 
 
o  Message # 23  - "CRC error"  Reason: Media access error.  Check the  
diskette or drive.  Functions returning this error: Bad or damaged diskette. 
 
o  Message # 24 - "Invalid length"  Reason: Media access error.  Check the  
diskette or drive. Functions returning this error: Bad or damaged diskette. 
 
o  Message # 25 - "Seek error"  Reason: Media access error.  Check the  
diskette or drive.  Functions returning this error: Bad or damaged diskette. 
 
o  Message # 27 - "Sector not found"  Reason: Media access error.  Check  
the diskette or drive.  Functions returning this error: Bad or damaged  
diskette. 
 
o  Message # 29 - "Write fault"  Reason: Media access error.  Check the  
diskette or drive.  Functions returning this error: Bad or damaged diskette. 
 
o  Message # 30 - "Read fault"  Reason: Media access error. Check the  
diskette or drive.  Functions returning this error: Bad or damaged diskette. 
 
o  Message # 31 - "General failure"  Reason:  Media access error.  Check  
the diskette or drive.  Functions returning this error:  Diskette may  
not be formatted. 
 
 
 
23.0 Scopes 
 
Chapter 22 discussed the software distribution script language  This  
chapter discusses the creation and management of scopes--the group of  
workstations defined to receive a distributed package. 
 
NOTE:  This chapter pertains to BrightWorks. 
 
 
23.1 Introduction 
 
A scope is a group of workstations defined to receive a distributed  
package.  Defining a scope is as easy as assigning a name to the new  
scope.  After the scope is created, any number of workstations can be  
included in the scope definition. 
 
23.1.1 Scope Features 
 
By taking advantage of the database of inventory information maintained  
by BrightWorks, users can create scopes by selecting from nodes that match  
specific filtering criteria.   
 
The filtering criteria is saved as a "query" and then applied against the  
database to narrow down the list of applicable workstations.  Scope  
membership is subsequently assigned using the list of nodes that match the  
user-specified filtering criteria.  Items such as CPU speed, workstation  
memory and installed software can be used to accommodate a scope's intent.   
For example, a scope named CPU386 might consist of the network's 386  
workstations; a scope named 386>16MHz might consist of the network's 386  
workstations that also have a CPU clock frequency greater than 16 MHz. 
 
Scopes and queries can be stored, used and reused as resources within  
BrightWorks.  A user can create a new scope, as well as edit, copy,  
rename and delete a scope.  The steps for managing both scopes and queries  
are provided in this chapter. 
 
23.1.2 Access to Scope Functions 
 
Scope functions are accessed by choosing the Scopes command from the  
Tools menu.  The Scopes dialog box displays listing all available scopes. 
 
23.1.3 What's in this Chapter 
 
The following chart describes the sections in this chapter: 
 
SECTION                 DESCRIPTION 
Creating Scopes         Describes procedures for defining new scopes. 
 
Scope Queries           Describes procedures for applying queries to  
			scopes, removing queries from scopes, creating  
			new queries, editing queries and deleting queries. 
 
Managing Scopes         Describes procedures for editing, renaming,  
			copying and deleting scopes. 
 
 
23.2 Creating Scopes 
 
Use the following procedure to create a new scope. 
 
NOTE:  At least one audit must have been run in order to create a scope. 
 
1.  Choose the Scopes command from the Tools menu. 
 
    The Scopes dialog box displays listing the names of all defined scopes.   
 
2.  Choose the New button. 
 
    The New Scope dialog box displays prompting you to enter a name for  
    the new scope.   
 
3.  Enter the new scope name, and choose the OK button. 
 
    A scope name can be up to 80 characters, and all typed characters are  
    valid.  For example, enter the new scope name "386/16MHZ" which will  
    include the network's 386/16MHz nodes. 
 
    Upon choosing the OK button, the Edit Scope dialog box displays  
    prompting you to define the new scope. 
 
    The Edit Scope dialog box consists of two lists: 
 
	o  Nodes in SITE - the list on the left side of the dialog box  
	consists of all node names that apply to the local site.  The  
	site name is indicated by the SITE text in the list title. The  
	nodes in this list are not included in the selected scope  
	(i.e., the list to the right).   
 
	o  Nodes included in Scope - the list on the right side of the  
	dialog box consists of the nodes that are in the selected scope.   
 
NOTE:  The Query Options section of the Edit Scope dialog box is used to  
perform a query to filter the node names in the Nodes in SITE list.   
For detailed instructions on performing queries, refer to the next  
section of this chapter entitled "Scope Queries." 
 
4.  Define the nodes to be included in the scope. 
 
    Use the push buttons in the center of the Edit Scope dialog box to  
    define the scope members.  To define scope membership, select a node  
    name from either list and choose the appropriate button: 
 
	o  Include >> - choose this button to include the selected node  
	in the scope.  The node name moves from the left list to the right  
	list. 
 
	o  Include All - choose this button to include all listed nodes in  
	the scope.  All node names move from the left list to the right list. 
 
	o  << Remove - choose this button to remove the selected node from  
	the scope.  The node name moves from the right list to the left list. 
 
	o  Remove All - choose this button to remove all nodes from the  
	scope.  All node names move from the right list to the left list. 
 
NOTE:  Because user names can be edited via the View Inventory Details  
dialog box, the node names in the Nodes in SITE list do not necessarily  
correspond to NetWare user names.  As a result, there may be duplicate  
names in this list.  Viewing the inventory details of nodes with the same  
name enables you to differentiate between the nodes.  Choose the View  
button or double click on a name in either list to invoke the View  
Inventory Details dialog box for the selected node.  
 
5.  When the scope members are defined, choose the Save button. 
 
 
23.3 Scope Queries 
 
When no filtering criteria is applied to a scope, all nodes in the  
local BrightWorks site are listed in the Nodes in SITE list of the Edit  
Scope dialog box.  This condition is indicated by the <None> entry in  
the Last Query field.   
 
Searching through a large list of nodes might make the process of  
defining scope membership cumbersome.  Applying a query to a scope refines  
the number of nodes in the Nodes in SITE list so that scope membership  
can be made from a "qualified" list of nodes. 
 
NOTE:  Only one query can be applied to a scope at any time.  Each query  
can consist of more than one filtering criteria.  An applied query  
always filters from the entire list of nodes in the local BrightWorks site. 
 
Queries can be saved and applied to any number of scopes.  The same queries  
can be applied to BrightWorks inventory and distribution reports, as is  
discussed in Chapter 18 of this manual. 
 
This section lists the procedures for: 
o  Creating a new query 
o  Editing a query 
o  Deleting a query 
o  Applying a query to the scope  
o  Removing a query from the scope  
 
23.3.1 Creating a New Query 
 
Use the following procedure to create a new query.  The procedure assumes  
that you have already chosen the Select button in the Edit Scope dialog  
box to display the Select Query dialog box. 
 
NOTE:  All queries are also available when generating BrightWorks  
inventory and distribution reports, as discussed in Part Three,  
Chapter 18 of this manual.  
 
1.  Choose the Add button in the Select Query dialog box. 
 
    The Add Query dialog box displays.  Press the <TAB> key to move  
    from field to field within this dialog box. 
 
2.  Enter a Query Name and define a filter entry. 
 
    The purpose of each filter entry is to narrow down the list of nodes  
    that apply to the specified criteria.  If more than one filter entry  
    is defined, the entries are "linked" using either the AND or OR  
    relationship.   
 
    For example, assume the following two filter entries: 
 
	Central Processing Unit = Intel_80386 
	CPU Clock Frequency > 66.00 Mhz 
 
    If the entries are linked with the OR relationship, only the nodes  
    that satisfy either criteria (i.e., all Intel 80386 machines and  
    all machines that have a clock speed greater than 66 Mhz) are  
    included in the database sort. 
 
    If the entries are linked with the OR relationship, the nodes that  
    satisfy either criteria (i.e., all 286 machines and all machines  
    that have a 720k floppy drive) are included in the database sort.  
 
    For each filter entry, specify the following: 
 
	o  Query Name - Enter a query name up to 80 characters in length. 
 
	o  Component - Choose a component from the BrightWorks inventory  
	database to use as the filter basis.  Select a component from the  
	drop-down list associated with this field (e.g., Brand, Computer  
	Model, CPU Clock Frequency). 
 
	o  Condition - Choose a conditional operator from the drop-down  
	list associated with this field (e.g., equal to, less than,  
	greater than, not equal to).  'Equal to' is the default condition. 
 
	o  Description - If desired, choose a description of the component.   
	The items which automatically display in this list depend on the  
	selected component.  For example, "Intel_80386" might display if  
	Central Processing Unit is entered in the Component field;  
	"16.00 Mhz" might display if CPU Clock Frequency is entered in the  
	Component field.  See Note (a) below. 
 
	o  Query Link - Specify the relationship between the filter  
	entries (e.g., Central Processing Unit = 80386 OR Central  
	Processing Unit = 80486).  The link options are AND and OR.   
	See Note (b) below. 
 
NOTES:  a - To create a query which tests for the presence of a  
component, leave the Description field blank.  For example, to include  
all nodes with a hard disk, construct a query with the following entries: 
 
	Component =  
	Hard Disk #1 < > 
 
In this case, the Component description is left blank, and the query  
results in including all nodes which have a hard disk (i.e., Hard Disk  
#1 does not equal blank). 
b - All filter entries in a query must have the same Query Link type  
(e.g., all entries will be linked by AND or all entries will be linked by OR). 
 
3.  Choose the Insert button to accept the filter entry definition. 
 
    The entry is added to the Current Query List in the Edit Query dialog box. 
 
4.  If required, insert additional filter entries.  
 
    Repeat steps #2 and #3 above. 
 
NOTE:  To add a filter entry between existing entries, first highlight  
the filter entry line in the Current Query list where you want the new  
entry to be placed.  The new defined entry is placed in the highlighted  
position. 
 
5.  When all filter entries are defined, choose the Save button. 
 
    The query is saved and added to the Available Queries list in the  
    Select Query dialog box.  The new query can now be applied to a scope. 
 
23.3.2 Editing a Query 
 
Use the following procedure to edit the definition of an existing query.   
The procedure assumes that you have already chosen the Select button in the  
Edit Scope dialog box to display the Select Query dialog box. 
 
1.  Select a query from the Select Query dialog box, and choose the Edit  
    button. 
 
    The Edit Query dialog box displays showing the defined filter entries  
    for the query. 
 
2.  Modify the filter information, and choose the Save button. 
 
    To delete a filter entry, highlight the entry in the Current Query  
    List and choose the Delete button. 
 
    To add a filter entry, specify the Component, Condition and Description,  
    and choose the Insert button.  (For detailed instructions on adding  
    filter entries, refer to the procedure above entitled "Creating a  
    New Query.") 
 
NOTE:  New filter entries are appended to the end of the Current Query  
List unless a filter entry is selected.  If an existing filter entry is  
selected, then the new filter entry gets inserted above it when you  
choose the Insert button. 
 
23.3.3 Deleting a Query 
 
Use the following procedure to delete an existing query.  The procedure  
assumes that you have already chosen the Select button in the Edit Scope  
dialog box to display the Select Query dialog box. 
 
1.  Select the query to be deleted from the Select Query dialog box, and  
    choose the Delete button. 
 
    A prompt displays asking you to confirm the deletion.   
 
2.  Choose the Yes button to delete the query. 
 
    If deleted, the query name is removed from the Available Queries list.   
 
NOTE:  Queries that are currently applied to a scope and/or BrightWorks  
inventory and distribution report can be deleted. 
 
23.3.4 Applying a Query to the Scope  
 
Use the following procedure to apply an existing query to a scope.  The  
procedure assumes that you have already chosen the Edit button in the  
Scopes dialog box to display the Edit Scope dialog box. 
 
1.  Choose the Select button in the Query Options section of the Edit  
    Scope dialog box. 
 
    The Select Query dialog box displays listing all defined queries. 
 
2.  Select the query name from the Available Queries list, and choose the  
    Apply button. 
 
    To select a query name, point to the query and click the left mouse  
    button.   
 
NOTE:  Applying a query to a scope causes a Printing Status dialog box to  
display while the database records are being sorted.  When this occurs,  
nodes are being selected (i.e., the information is not being sent to the  
printer). 
 
    The Select Query dialog box closes, and the selected query name is  
    placed into the Last Query field of the Edit Scope dialog box.  The  
    BrightWorks database records are sorted, and only the records that  
    match the query's specified filter criteria will display in the Nodes  
    in SITE list.  Now you can assign scope members using a "qualified"  
    list of nodes. 
 
NOTE:  If you already selected nodes to be included in the scope  
(i.e., the nodes listed in the Nodes Included in Scope list), the nodes  
continue to be "included" even if they do not match the filter criteria.   
 
23.3.5 Removing a Query from the Scope 
 
Use the following procedure to remove a scope query.  
 
1.  Choose the Select button in the Query Options section of the Edit  
    Scope dialog box. 
 
    The Select Query dialog box displays. 
 
2.  Select the <None> query name, and choose the Apply button. 
 
    The Select Query dialog box closes.  All nodes in the local BrightWorks  
    site are listed in the Nodes in SITE list of the Edit Scope dialog box. 
 
23.3.6 Creating a Complex Query 
 
A query can consist of any number of filter entries that are defined to  
produce a desired result.  The relationship between the filter entries is  
referred to as the "link." 
 
Assume that you are responsible for upgrading the workstations of all  
network users in the Sales Department who are currently using Intel 286  
machines with a CPU speed less than 16 MHz and which have a 1.44 megabyte  
floppy disk designated as drive A:.   
 
Use the following procedure to create a query that defines the scope of  
users in the above example. 
 
1.  In the Add Query dialog box, enter a Query Name.  
 
    Enter a name that uniquely identifies this query  
    (e.g., "Sales 286/16Mhz"). 
 
2.  Define the first filter entry, and choose the Insert button. 
 
    Enter the following for each field: 
 
	Component: Department 
	Condition: = 
	Description: Sales 
	Query Link: AND 
 
3.  Define the second filter entry, and choose the Insert button. 
 
    Enter the following for each field: 
 
	Component: Central Processing Unit 
	Condition: = 
	Description: Intel_80286 
	Query Link: AND 
 
4.  Define the third filter entry, and choose the Insert button. 
 
    Enter the following for each field: 
 
	Component: CPU Clock Frequency 
	Condition: < 
	Description: 16MHz 
	Query Link: AND 
 
5.  Define the fourth filter entry, and choose the Insert button. 
 
    Enter the following for each field: 
 
	Component: Floppy Disk #1 
	Condition: = 
	Description: A: 1.44 M 
	Query Link: AND 
 
6.  Choose the Save button to save the query. 
 
    The filter entries in the Current Query list in the Edit Query  
    dialog box should be identical to the following: 
 
	Department = Sales 
	Central Processing Unit = Intel_80286    AND 
	CPU Clock Frequency < 16MHz      AND 
	Floppy Disk #1 = A: 1.44 M       AND 
 
 
 
23.4 Managing Scopes 
 
23.4.1 Editing Scopes 
 
Editing a scope may become necessary under two circumstances: 
 
o  Existing scopes might need to be edited in order to add or delete  
members according to a change in a scope's intent. 
 
o  Scopes that are attached to packages might need to be edited when  
re-sending packages. 
 
Scope members are the nodes that are defined as a group to receive a  
distributed package.   
 
NOTE:  An existing scope can be edited even if the scope is part of a  
scheduled package.  This is useful if you need to re-send a package to  
a node(s).  If new nodes are added to a scope that is included in an  
active package, then the package will automatically get distributed to  
the new nodes. 
 
Use the following procedure to edit a scope.  The procedure assumes that  
you have already chosen the Scopes command from the Tools menu to  
display the Scopes dialog box. 
 
1.  Select the scope from the list of Scopes, and choose the Edit button. 
 
    A scope can also be selected for editing by double clicking on the  
    scope name in the Scopes dialog box.  The Edit Scope dialog box displays. 
 
    The Edit Scope dialog box consists of two lists: 
 
	o  Nodes in SITE - the list on the left side of the dialog box  
	consists of all node names that apply to the local site.  The  
	site name is indicated by the SITE text in the list title.  The  
	nodes in this list are not included in the selected scope  
	(i.e., the list to the right).   
 
	o  Nodes included in Scope - the list on the right side of the  
	dialog box consists of the nodes that are in the selected scope.   
 
NOTE:  The Query Options section of the Edit Scope dialog box is used  
to perform a query to filter the node names in the Nodes in SITE list.   
for detailed instructions on performing queries, refer to section 23.3 
entitled "Scope Queries." 
 
2.  Define the nodes to be included in the scope. 
 
    Use the push buttons in the center of the Edit Scope dialog box to  
    define the scope members.  To define scope membership, select a node  
    name from either list and choose the appropriate button: 
 
	o  Include >> - choose this button to include the selected node  
	in the scope.  The node name moves from the left list to the right  
	list. 
 
	o  Include All - choose this button to include all listed nodes  
	in the scope.  All node names move from the left list to the right  
	list. 
 
	o  << Remove - choose this button to remove the selected node  
	from the scope.  The node name moves from the right list to the  
	left list. 
 
	o  Remove All - choose this button to remove all nodes from the  
	scope.  All node names move from the right list to the left list. 
 
NOTE:  Because user names can be edited via the View Inventory Details  
dialog box, the node names in the Nodes in SITE list do not necessarily  
correspond to NetWare user names.  As a result, there may be duplicate  
names in this list.  Viewing the inventory details of nodes with the same  
name enables you to differentiate between the nodes.  Choose the View  
button or double click on a name in either list to invoke the View Inventory  
Details dialog box for the selected node.  
 
3.  When the scope members are defined, choose the Save button. 
 
23.4.1 Renaming Scopes 
 
Use the following procedure to rename a scope.  The procedure assumes  
that you have already chosen the Scopes command from the Tools menu to  
display the Scopes dialog box. 
 
NOTE:  A scope can be renamed even if it is part of an actively scheduled  
package. 
 
1.  To rename a scope, select the scope from the list of Scopes, and  
    choose the Rename button. 
 
    The Rename Scope dialog box displays prompting you to enter a new  
    scope name. 
 
2.  Enter the new scope name, and choose the OK button. 
 
    The new scope name displays in the Scopes dialog box, and the old  
    name is removed.  All attributes of the old scope are preserved in the  
    renamed scope (i.e., the scope members do not change). 
 
23.4.2 Copying Scopes 
 
Use the following procedure to copy a scope.  The procedure assumes  
that you have already chosen the Scopes command from the Tools menu to  
display the Scopes dialog box. 
 
NOTE:  A scope can be copied even if the original scope is part of an  
actively scheduled package. 
 
1.  To copy a scope, select the scope from the list of Scopes, and  
    choose the Copy button. 
 
    The Copy Scope dialog box displays prompting you to enter a name for  
    the new scope. 
 
2.  Enter the new scope name, and choose the OK button. 
 
    The new scope name is added to the Scopes dialog box.  The new scope  
    members are identical to the original scope members. 
 
 
23.4.3 Deleting Scopes 
 
Use the following procedure to delete a scope.  The procedure assumes  
that you have already chosen the Scopes command from the Tools menu to  
display the Scopes dialog box. 
 
NOTE:  A scope that is part of a scheduled package cannot be deleted. 
 
1.  To delete a scope, select the scope from the list of Scopes, and  
    choose the Delete button. 
 
    A prompt displays asking you to confirm the deletion. 
 
2.  Choose the Yes button to delete the scope. 
 
    If deleted, the scope name is removed from the Scopes dialog box.   
 
 
 
24.0 Packages 
 
Chapter 23 discussed the creation and management of scopes.  This chapter  
discusses the creation and management of packages--the method by which  
software is distributed across your network. 
 
NOTE:  This chapter pertains to BrightWorks. 
 
 
24.1 Introduction 
 
Creating and activating a package is the method by which software is  
distributed across your local area network.  When a package is created,  
it is assigned a scope and a "Start Date."  Upon reaching the start date  
and running the SDUPDATE.EXE program at a workstation in the scope, an  
active package automatically gets sent to the workstation. 
 
A package also consists of a fileset and/or a script to be distributed to  
the group of remote workstations.  For example, a package named  
UPGRADE_DOS might include a scope of users running DOS 3.3.  The package  
might also include a script which installs a fileset consisting of the  
DOS 6.0 files. 
 
The software distribution update program (SDUPDATE.EXE) is integrated  
with the packaging functionality.  The update program is responsible for  
determining the conditions for accepting or rejecting a package.  The  
program is also responsible for reporting on package status as input to the  
Packages window and the Software Distribution Log. 
 
24.1.1 Package Features 
 
In addition to the contents and scope, every package is assigned a schedule  
and a method for delivery.  A package's schedule is the date on which the  
package is to be distributed.  The method of delivery specifies instructions  
for the receiving workstation.  There are several options available to  
the workstation user when a package is received.  For example, package  
ABC might be configured to prompt the user five times to accept the  
package before proceeding with the installation of its fileset.   
 
A user can create a new package, as well as edit, rename and delete a  
package.  The steps for each procedure are discussed in this chapter.  
 
24.1.2 Access to Package Functions 
 
Most package functions are accessed by either: 
 
o  choosing the Packages command from the Tools menu, or 
o  choosing the Distribute tool bar button  
 
Both of the above actions cause the Packages window to display.   
 
Package management is performed by either choosing the buttons in the  
Packages window or by choosing the corresponding commands from the File  
menu.  For example, when the Packages window is active, a new package  
can be created either by choosing the New button in the Packages window  
or by choosing the New Package command from the File menu.   
 
The information in the Packages window is updated according to an  
interval called the "package timer."  Package timer functions are accessed  
by choosing the Distribution command from the Administration menu.  
 
24.1.3 What's in this Chapter 
 
The following chart describes the sections in this chapter: 
 
SECTION                         DESCRIPTION 
Creating and Editing Packages   Describes procedures for defining new  
				packages and for editing existing packages. 
 
Managing Packages               Describes procedures for renaming,  
				activating/deactivating, and deleting  
				packages. 
 
The Package Timer               Describes procedures for setting the  
				package timer interval. 
 
 
 
24.2 Creating and Editing Packages 
 
Use the following procedure to create a new package. 
 
1.  Choose the Packages command from the Tools menu, or choose the  
    Distribute tool bar button. 
 
    The Packages window displays.  This window lists the names of all  
    defined packages.  For each package, the following is indicated:  
 
	o  Start Date - the date the package will be distributed 
	o  Status - the package's status (Active or Inactive) 
	o  Total - the total number of workstation in the package's scope 
	o  Done - the number of successful updates so far 
	o  Errors - the total number of failed attempts at performing  
	an update 
 
NOTE:  Packages that have the same Start Date are distributed in the  
order in which they appear in the Packages window.  To change a  
package's priority, refer to section 24.3.1 entitled "Prioritizing  
Packages."  
 
2.  Choose the New button in the Packages window. 
 
    The New Package dialog box displays prompting you to enter a name  
    for the new package. 
 
3.  Enter the new package name, and choose the OK button. 
 
    The package name can be up to 80 characters, and all typed characters  
    are valid. 
 
    Upon choosing OK, a New Package dialog box displays.  The name of the  
    new package is indicated in the title bar of the dialog box. 
 
4.  Select a fileset and/or a script to be included in the package. 
 
    Choose the down arrow button to the right of the Update Fileset  
    and/or Update Script fields to display the list of existing filesets  
    and scripts.  Select the desired items from the drop-down lists. 
 
NOTE:  A package must include either one fileset or one script, or both. 
 
5.  Select the scope to receive the package. 
 
    Choose the down arrow button to the right of the Update Scope field  
    to display the list of existing scopes.  Select a scope from the  
    drop-down list. 
 
NOTE:  A scope must be assigned to the package. 
 
6.  Assign the package's Start Date. 
 
    Enter the date on which the package is to be distributed.  The current  
    date appears as a default in this field.  Use the up/down arrow buttons  
    to the right of the Start Date field to scroll to the desired date,  
    or press the <F4> key to display a calendar from which a date can be  
    selected. 
 
7.  Assign the Active or Inactive status to the package. 
 
    Check the "Update active when saved" option to automatically place  
    the package in an active state upon saving the package.  (An active  
    package will get distributed automatically on its assigned start date.) 
 
    If this field is not checked, an Inactive status will be assigned to  
    the package.  An inactive package will not get distributed  
    automatically on its assigned start date. 
 
8.  Specify the package's update option. 
 
    The selected Update Option instructs the software distribution update  
    program how it should interact with the receiving workstation user at  
    login time. 
 
    The four Update Options are: 
 
	o  Force upgrade at next login - This option forces the package's  
	receipt on the user at the next login.  If an error occurs, the  
	distribution is halted so the administrator can address the  
	problem and reschedule the package. 
 
	o  User optional until [DATE] and then [ABANDON, FORCE] update -  
	This option allows the user to refuse the package until the  
	indicated DATE.  After the DATE, the package is either abandoned  
	or forced to be received by the user. 
 
	o  User optional, prompt user [# TIMES] and then [ABANDON, FORCE]  
	update - This option allows the user to refuse the package a  
	certain number of times (# TIMES).  After the threshold is reached,  
	the package is either abandoned or forced to be received by the user. 
 
	o  Run this package always - This option forces the package's  
	receipt on the user at each and every login.  This update option  
	is most useful in situations where system variables are being  
	modified directly by users. 
 
9.  Specify the target path in which the fileset should be decompressed. 
 
    A default path must be assigned to the package.  The default path is  
    the target path in which the distributed software (i.e., fileset) is  
    to be installed or copied.   
 
    The default path can be: 
 
	o  entered as a hard-coded drive mapping and directory  
	combination (e.g., C:\BIN\DRIVERS). 
 
	o  entered as a hard-coded server, volume and directory  
	combination (e.g., SERVER/VOLUME:\DIR or VOLUME:\DIR).  If a  
	server is specified, then the user receiving the package must be  
	attached to the server. 
 
	o  reliant upon a system configuration found at the receiving  
	workstation.  Reliance is implemented by using one of the following  
	target default path options available from the drop down list  
	associated with this field: 
 
		- [BOOT_ROOT] - the root of the receiving machine's boot  
		disk 
		- [HDRIVE] - the receiving machine's first hard drive 
		- [NDRIVE] - the receiving machine's first network drive 
		- [NETCFG] - path to the receiving machine's network  
		configuration (which must be in the path) 
		- [WINDIR] - the receiving machine's Windows directory  
		(the directory in which the login module finds WIN.INI -  
		this directory must be in the path) 
		- [WINSYSDIR] - the receiving machine's Windows\System  
		directory (directory in which the login module finds  
		USER.EXE - this directory may be in the SYSTEM directory  
		below WINDIR, or in the path) 
 
    These variables can be used in combination with a hard-coded value  
    (e.g., [WINSYSDIR]\TEMP).  In this case, the backslash character (\)  
    is required and the variable name must be first.  If a specified  
    directory does not exist, it will be created. 
 
    If desired, check the "Allow user to override installation path" option  
    to allow the user at the receiving workstation to override the selected  
    path. 
 
10. To define advanced package options, choose the Advanced button. 
 
    The Advanced Options dialog box displays.  The advanced package  
    options consist of the following categories: 
 
    o  Windows Error Options - options associated with how the software  
    distribution update program should react in the event that the Windows  
    directory is not discovered at a receiving workstation. 
 
    o  Fileset and Script Options - options which define the execution  
    precedence for the package's fileset and script  (e.g., which one  
    the software distribution update program should run first at the  
    receiving workstation).  
 
    o  Script Error Options - options associated with how the software  
    distribution update program should react in the event of script errors.    
    (The script function error codes are detailed in Chapter 22 of this  
    manual, "Software Distribution Script Language.") 
 
NOTE:  Several script functions may return a non-zero value that is not  
considered to be an error.  For example, the FINDFILE function returns  
a -1 if the file is not found; the STRCOMPARE function returns non-zero  
value if the two strings are not equal.  You might want to disable the  
Script Error Options when using functions that return non-zero values even  
when successful. 
 
11. When all package attributes are defined, choose the Save button. 
 
24.2.1 Editing Packages 
 
Editing a package may be necessary in order to modify package attributes. 
 
Use the following procedure to edit the attributes of a package.  The  
procedure assumes that you have already chosen the Packages command from  
the Tools menu to display the Packages window. 
 
1.  To edit package attributes, select the package from the Packages  
    window, and choose the Edit button. 
 
    A package can also be selected for edit by double clicking on the  
    package name in the Packages window.  The Edit Package dialog box  
    displays showing the configuration of the selected package.  The  
    fields and options in this dialog box are identical to the New Package  
    dialog box. 
 
    The name of the package being edited displays in the title bar of  
    the Edit Package dialog box. 
 
2.  Modify the package attributes. 
 
    Changes can be made to any field except the Update Scope, Update  
    Fileset and Update Script fields. 
 
NOTES: a - Although the package's scope, fileset and script cannot be  
changed, their definition can be changed.  For example, if Scope ABC  
is assigned to the package, you cannot assign Scope XYZ to the package  
but you can edit the members of scope ABC. 
b - If a package fails, it can be re-distributed to a user by first  
removing the user from the scope and saving the edited scope, and then  
adding the user back into the scope and again saving the edited scope.   
Be careful when doing this because editing a scope changes all instances  
of the scope (i.e., even those included in packages).  
 
    If the distribution of a package has already begun, the changes made  
    to the package take effect on the next node in the scope to receive  
    the package. 
 
3.  Choose the Save button. 
 
    The Packages window re-displays.  
 
NOTE:  To display the Software Distribution Log History details  
associated with a package, highlight the package in the Packages window  
and choose the Details button.  The Log Details dialog box displays  
showing the details for the selected package.  This dialog box is discussed  
in Chapter 25. 
 
 
24.3 Managing Packages 
 
24.3.1 Prioritizing Packages 
 
The priority with which each package is run is determined by its position  
in the Packages window.  Packages that have the same Start Date are  
distributed in the order in which they are listed. 
 
To modify a package's run time, highlight the package in the Packages  
window, and choose either the Up or Down buttons.  The highlighted package  
will be moved in the selected direction. 
 
For example there are two packages scheduled to be distributed on  
1/12/1994.  Because of their position in the list of packages, WIN_INI  
will be distributed before UPDATED SYSTEM FILES.  To change their  
distribution order, highlight the UPDATED SYSTEM FILES fileset and  
choose the up arrow button.  
 
Also note that the status of the TUTORIAL package is "Complete (A)."   
The (A) indicates that although the package has been distributed to all  
workstations in the scope, the package is still active.  Therefore, if  
the package's scope is edited to include additional nodes, the package will  
automatically get distributed to those new nodes. 
 
24.3.2 Renaming Packages 
 
Changing the name of an existing package renames the package in the  
Packages window. 
 
Use the following procedure to rename a package.  The procedure assumes  
that you have already chosen the Packages command from the Tools menu  
to display the Packages window. 
 
NOTE:  Actively scheduled packages can be renamed. 
 
1.  To rename a package, select the package from the Packages list, and  
    choose the Rename button. 
 
    The Rename Package dialog box displays prompting you to enter a new  
    package name. 
 
2.  Enter the new package name, and choose the OK button. 
 
    The new package name displays in the Packages window, and the old  
    name is removed.  All attributes of the old package are preserved in  
    the renamed package (i.e., the package's scope, script and/or fileset  
    definitions do not change). 
 
24.3.3 Activating/Deactivating Packages 
 
New packages are assigned the Active status if the Update Active when  
Saved option is selected.  An active package automatically gets distributed  
upon reaching its assigned Start Date.  An inactive package will not get  
distributed until it is re-activated. 
 
The status indication of a selected package in the Packages window  
toggles between Active/Inactive by choosing the Activate/Deactivate  
toggle button in the Packages window. 
 
The status of a completed package (i.e., a package that has been sent to  
all nodes in its scope) remains active.  Its status is indicated by  
"Complete (A)."  By highlighting the completed package and choosing the  
Deactivate toggle button, the status changes to "Complete (I)" which  
indicates an inactive status. 
 
24.3.4 Deleting Packages 
 
Use the following procedure to delete a package.  The procedure assumes  
that you have already chosen the Packages command from the Tools menu to  
display the Packages window. 
 
NOTE:  Actively scheduled packages cannot be deleted.  To delete a package  
with an Active status, first make the package status Inactive by  
highlighting the package and choosing the Deactivate button.  Then  
perform the Delete action. 
 
1.  To delete a package, select the package from the Packages window,  
    and choose the Delete button.  
 
    A prompt displays asking you to confirm the deletion. 
 
2.  Choose the Yes button to delete the package. 
 
    If deleted, the package name is removed from the Packages window.   
 
NOTE:  Deleting a package does not delete the associated log entry in  
the Software Distribution Log History dialog box. 
 
 
24.4 The Package Timer 
 
The Packages window displays the status of each scheduled package.   
Status information includes the number of workstations in the package's  
scope (Total), the current number of successful updates (Done) and the  
total number of failed attempts at performing an update (Errors).  The  
window contents are updated according to a defined package timer interval.   
 
Use the following procedure to set the package timer and define the  
interval at which the Packages window data is updated. 
 
1.  Choose the Distribution command from the Administration menu.  From  
    the sub-menu that displays, choose the Set Package Timer command. 
 
    The Set Package Timer dialog box displays.  
 
2.  Enter the time interval at which the Packages window should be  
    updated, and choose the OK button. 
 
    Enter the time in seconds.  (The default is 30 seconds.)  The  
    information in the Packages window will be updated at the defined  
    interval. 
 
NOTE:  The status of the Packages window can also be updated on demand  
by choosing the Distribution command from the Administration menu.   
From the sub-menu that displays, choose the Query Now command. 
 
 
 
25.0 Monitoring Software Distribution 
 
Chapter 24 discussed the creation and management of packages.  This  
chapter discusses the procedures for using the Software Distribution Log  
History dialog box to monitor the success of distributed packages. 
 
NOTE:  This chapter pertains to BrightWorks. 
 
 
25.1 Introduction 
 
The chronological events associated with scheduled packages can be  
viewed from the Software Distribution Log History dialog box.  The log  
history provides the information necessary for monitoring the success or  
failure of a distributed package.  For example, if package WINUPDATE is  
distributed to a scope having three members, the installation of the  
software and update details for all three receiving workstations can be  
verified via the log history details. 
 
25.1.1 Access to the Software Distribution Log 
 
The Software Distribution Log History dialog box is displayed by choosing  
the Distribution command from the Administration menu.  From the sub-menu  
that displays, choose the View Distribution Log command. 
 
The Software Distribution Log History dialog box is also displayed by  
choosing the Details button in the Packages window. 
 
25.1.2 What's in this Chapter 
 
The following chart describes the sections in this chapter: 
 
SECTION                         DESCRIPTION 
The Software Distribution Log   Describes procedures for viewing and  
				maintaining Log history details. 
 
 
25.2 The Software Distribution Log 
 
25.2.1 Viewing Log History Details 
 
Use the following procedure to monitor and maintain the log history of  
distributed packages. 
 
1.  Choose the Distribution command from the Administration menu.  From  
    the sub-menu that displays, choose the View Distribution Log command. 
 
    The Software Distribution Log History dialog box displays.  The history  
    log provides a summary of all scheduled packages.  The following  
    information is provided for each package:  
 
	o  Start Date - the date the package will be distributed 
	o  Total - the total number of workstation in the package's scope 
	o  Done - the number of successful updates so far 
	o  Errors - the total number of failed attempts at performing an  
	update 
 
NOTE:  The completed updates (Done column) may be greater than the number  
of users scheduled to receive a package (Total column).  This can occur as  
a result of rescheduling packages or when using the "Run this package always"  
update option during package scheduling. 
 
2.  To view the individual events of a package, select the package from  
    the Software Distribution Log History dialog box, and choose the  
    Details button. 
 
    A package can also be selected by double clicking on the package name  
    in the Software Distribution Log History dialog box.  The Log Details  
    dialog box for the selected package displays. 
 
    In addition to the distribution Date/Time and target Site Name, the  
    Details of the package's chronological events are shown in three lines: 
 
	o  Identification of the target workstation - node address, user name 
	o  Additional target workstation information - location, asset tag 
	o  Results - some possible results are:  
		- Package installed successfully. 
		- Error [#]: Script "[Script name]" has not been  
		completed successfully.  
 
NOTE:  The error numbers related to unsuccessful script execution are  
documented in Chapter 22 of this manual, "Software Distribution Script  
Language."  Non zero error numbers only display if the corresponding  
option was selected when the package was created.  For instructions on  
defining "advanced package options," refer to the previous chapter. 
 
3.  To delete a log entry, select the package from the Software  
    Distribution Log History dialog box, and choose the Delete button. 
 
    The package is removed from the list of scheduled packages.  
 
NOTE:  A log entry cannot be deleted if its associated package still exists. 
 
4.  Choose the OK button to close the Software Distribution Log History  
    dialog box. 

