XBatch   Guide   by techkn@ck    
downloads Download with full source
General download help
Installation Files Enter code to create installation files:

XBatch #

drawX

       back to HackKn@ck
Download

Introduction
Shapes: drawLine line joining two points
drawPolygon closed polygon linking a number of points
drawRectangle rectangle from top left corner and width and height
drawEllipse ellipse from centre, horizontal axis and axis ratio
Operations: zap delete a shape
zapAll delete all shapes
change shape colour example of shape manipulation
Examples


Introduction

drawX is a simple JavaScript file for drawing lines and shapes, usually over a background image.
It requires no further programs or files.


drawLine     draw a line joining two points

lvl   level (e.g. 1)

If the debug level is greater than zero, before each command is executed the operator is asked if the program should continue or terminate.


Goto     jump unconditionally to the given label

goto   label string (optional)


Any command may have a label parameter (e.g. see Null below).

If the given label is Abort, the commands are not scanned for the label. Instead XBatch just terminates.

If the given label does not exist, the error message
Missing label
is displayed, followed by the label name. The XBatch program then terminates.

The Exist, NotExist, Version, and OSVsn commands may also contain a goto parameter, which is processed conditionally in the same way.


Null     do nothing

label   any string


e.g. DOM code:
XCmd( x, "NotExist" );
x.XaddYT( "src", "£E\\Release\\" +sMyApp +".exe" );
x.XaddYT( "goto", "NoExe" );
. . .
. . .
. . .
XCmd( x, "Null" );
x.XaddYT( "label", "NoExe" );


CurrentFolder     change current folder

dst   path to folder

If the given folder does not exist, it is created.


OSVsn     Test Windows Version

The MFC functiom GetVersionEx sets the following fields:
dwPlatformId dwMajorVersion dwMinorVersion Combined
W3.1 0 ? ? 0???
W95 1 4 0 1400
W98 1 4 10 1410
ME 1 4 90 1490
 
NT3...2 3 ? 23??
NT4 2 4 0 2400
2000 2 5 0 2500
XP 2 5 1 2501
2003 2 5 2 2502
Vista 2 6 0 2600
W7 2 6 1 2601
 
CE 3 ? ?
Vista and Windows 7 can mimic other versions - see Microsoft Technet: Versioning Issues.

These fields are combined to form a single number:
(dwPlatformId *1000) +(dwMajorVersion *100) +dwMinorVersion
which is tested against a given code using one of the comparisons eq ne ge gt le lt.

eq   given code. Message/goto if OS vsn equals given code.
ne   given code. Message/goto if OS vsn does not equal to the given code.
ge   given code. Message/goto if OS vsn is greater than or equal to the given code.
gt   given code. Message/goto if OS vsn is greater than the given code.
le   given code. Message/goto if OS vsn is less than or equal to the given code.
lt   given code. Message/goto if OS vsn is less than the given code.
text   message to display if above test is true
 together with any of the other Message parameters.
goto   label (if no message) to go to if above test is true.

eg. To test for ME or earlier:
<X><Cmd>OSVsn</Cmd><le>1999</le><goto>W9xOrME</goto></X>
and the corresponding DOM code is
XCmd( x, "OSVsn" );
x.XaddYT( "le", "1999" );
x.XaddYT( "goto", "W9xOrME" );
- followed by the commands to do if the OS is NT3 or later.


Browse     Find or Create a Folder

title specifies the text that appears in the navigation box. Default is Pick a folder.
dstEnd If present, specifies the final folder name in the path to the application files,
and the operator must select the path up to, but not including, the final folder.
If the final folder does not already exist, it is created.
If not present, then the operator must specify the full path,
and may have to choose a name for the app folder, and create it.
installIf present, specifies the folder to be used as working storage during an installation.
flags node contains the OR merge of the required flags from the following:
0x0001 1  Only return file system directories.
If the user selects folders that are not part of the file system, the OK button is grayed.
Note The OK button remains enabled for "\\server" items, as well as "\\server\share" and folders.
However, if the user selects a "\\server" item, the operation fails at a later stage.
0x0002 2  Do not include network folders below the domain level in the dialog box's tree view control.
0x0008 8  Only return file system ancestors.
An ancestor is a subfolder that is beneath the root folder in the namespace hierarchy.
If the user selects an ancestor of the root folder that is not part of the file system, the OK button is grayed.
0x0010 16  Include an edit control in the browse dialog box that allows the user to type the name of an item.
0x0040 64  Setting this flag provides the user with a larger dialog box that can be resized,
has drag-and-drop capability within the dialog box, reordering, shortcut menus,
new folders, delete, and other shortcut menu commands.
0x0200 512  Do not include the New Folder button in the browse dialog box.
0x1000 4096  Only return computers. If the user selects anything other than a computer, the OK button is grayed.
0x4000 16384 The browse dialog box displays files as well as folders.
See msdn: Browse Info Structure for full list.
If editing the XML file directly, add up the decimal values for the required flags.


eg. To navigate just folders, include an edit box, and use the extended dialog (1+16+64 = 81):
<X><Cmd>Browse</Cmd><flags>81</flags><title>Select folder to contain WindList</title><dstend>WindList</dstend></X>
and the corresponding DOM code:
XCmd( x, "Browse" );
x.XaddYT( "flags" , String( 0x1 +0x10 +0x40) );
x.XaddYT( "title" , "Select folder to contain " +sMyApp );
x.XaddYT( "dstEnd", sMyApp );


NewFolder     Create a Folder

dst   path to folder
e.g. DOM code:
XCmd( x, "NewFolder" );
x.XaddYT( "dst", "£S\\" +sMyApp );

There is no error if the folder already exists.
Otherwise if the MFC function _mkdir returns an error code, an error message is displayed, eg.
Could not create folder C:\Program Files\MyApp Error code 123


DelFolder     Delete a folder

dst   path to folder
e.g. DOM code:
XCmd( x, "DelFolder" );
x.XaddYT( "dst", "£S\\" +sMyApp );

There is no error if the folder or the path does not exist.
Otherwise if the MFC function _rmdir returns an error code, displays the message eg.
Could not delete folder C:\Program Files\MyApp Error code 123


Copy     Copy a File, overwriting any existing file with the same name

src   path and source file
dst path and destination file
e.g. DOM code:
XCmd( x, "Copy" ); x.XaddYT( "src", "£IXBatch.exe" ); x.XaddYT( "dst", "£E\\XBatch.exe" );;

If the MFC function CopyFile returns zero (indicating an error), an error message is displayed, eg.
Could not write to file abc.xyz Error number 123


CopyX     copy file if destination file does not already exist

src   path and source file
dst   path and destination file
Error messages etc as for Copy.

Delete     delete a file

dst   path and file name

If the path or file does not exist, or the file is in use, an error message is displayed, eg.
Failed to delete abc.xyz Error number 123


Exist     Test if a file exists

src   path and file name
text   message to display if file exists
 together with any of the other Message parameters.
goto   label (if no message) to go to if file exists.


NotExist     Test if a file does not exist

src   path and file name
text   message to display if file does not exist
 together with any of the other Message parameters.
goto   label (if no message) to go to if file does not exist.


Version     test file version

This command is used mainly to test versions of files from the Windows folder.
Since the required versions will often be different for W9x systems, two groups of version numbers can be specified, and the group used depends on current Windows OS .
If the required version numbers are not supplied for the current OS, all versions of the file are assumed to be satisfactory.

src   file path and name
vaM   W95, W98, WMe   Major version number, ms word (16 bits)
vbM      Major version number, ls word
vcM      Minor version number, ms word (16 bits)
vdM      Minor version number, ls word
vaN   NT4, W2K, Xp etc.   Major version number, ms word (16 bits)
vbN      Major version number, ls word
vcN      Minor version number, ms word (16 bits)
vdN      Minor version number, ls word
text   message to display if file version is not adequate
 together with any of the other Message parameters.
goto   label (if no message) to go to if file version is not adequate.

If the file does not exist, or version information is not available, one of the following error messages will be displayed:
No version information for xxxxxx.yyy
Cannot get version information for xxxxxx.yyy
Cannot obtain version information for xxxxxx.yyy
otherwise the required and aqctual versions are compared.
If the file version is earlier than required, the following message is displayed:
xxxxxx.yyy
Vsn 123.456.78.90
Min 234.567.89.10
and the operator is asked if the program should continue or be terminated.


Sleep     sleep for given number of milliseconds

ms   Number of milliseconds to delay (to e.g. ensure a previous operation completes)


Shortcut     create a shortcut to an application

prog   path and program to run (without parameters)   "£E\\XBatch.exe"
params   parameters, or ""   "£E\\MyAppUnst.xml"
folder   working directory, or ""   "£E"
link   where to put the link file
The stem of the file name is what appears in the Start Menu, etc.  		 "£S\\MyApp\\Uninstall MyApp.lnk"
icon   path to icon, or ""   "£E\\RES\\MyAppUnst.ico"
desc   description displayed when hover over link, or ""   "Delete the Start Menu shortcuts and remove MyApp"


RegDel     delete a Registry entry

key   Registry key


The key must start with one iodf the following:
HKEY_CLASSES_ROOT\\
HKEY_CURRENT_CONFIG\\
HKEY_CURRENT_USER\\
HKEY_LOCAL_MACHINE\\
HKEY_USERS\\

If the key is not found, or cannot be deleted, the following error message is displayed, and the operator is asked if the program should continue or abort:
Failed to delete Registry key xxxxxxx Error code 123 Continue?


SetEnvironmentVariable     set environment variable

key   environment variable name
value   environment variable data string


ExtendXml     extend an XML file

xml   path and name of XML file
tagA   outer node name (if new XML file)
tag   node (child of outer node) to add
text   new node data


If the XML file could not be loaded, the following error message is displayed:
Could not access xxxxxx.xml
or if the new node and data could not be written:
Could not extend xxxxxx.xml


AmendXml     amend an XML file

xml   path and name of XML file
tagA   outer node name (if new XML file)
tag   node (child of outer node) to add
text   new node data


If the XML file could not be loaded, the following error message is displayed:
Could not access xxxxxx.xml
or if the node could not be found or the new data could not be written:
Could not amend xxxxxx.xml


Spawn     start another program

This command calls the Microsoft function _spawnl.
- The parameters to the program to be run are supplied as separate parameters to _spawnl rather than as a single string.
src   path and program file to run
params   1st parameter (optional)
param2   2nd parameter (optional)
param3   3rd parameter (optional)
param4   4th parameter (optional) (optional)
param5   5th parameter
wait   1 to wait for completion, else no wait


If _spawnl returns an error, the error message displayed will start with one of:
Program To Run not found
Program To Run not executable
Program To Run needs more memory
Invalid argument
Argument exceeds 1024 bytes
Unknown error
followed by the program name and the first two parameters.


Shell     start another program or open a file

This command calls the Microsoft function ShellExecute.
- The parameters to the program to be run are supplied as a single string.
src   path and file to run or open
params   all parameters (optional)


If ShellExecute returns an error, the error message displayed will start with one of:
Out of memory or resources
File not found
Path was not found
Invalid .exe file
Access denied
Invalid file name association
DDE transaction failed
DLL not found
Sharing violation
Unknown error
followed by the program name and the parameters.


Run     start another program

This command calls the Microsoft function CreateProcess.
- The program path and file name and parameters are supplied as a single string.
run  path and program and parameters
folder  working folder (optional)
wait  N not to wait for completion,
 anything else, or omitted, to wait.
show  hide to hide the console window (DOS box)
 min start with window minimised
 show or omitted start with window displayed normally


If CreateProcess returns an error, the error message displayed will be the run string, followed by failed to start..
- The XBatch program will then terminate.


Message     display a message

buttons
"AbortRetryIgnore" MB_ABORTRETRYIGNORE three pushbuttons: Abort, Retry, and Ignore
"OkCancel" MB_OKCANCEL two pushbuttons: OK and Cancel.
"RetryCancel" MB_RETRYCANCEL two pushbuttons: Retry and Cancel.
"YesNo" MB_YESNO two pushbuttons: Yes and No.
"YesNoCancel" MB_YESNOCANCEL three pushbuttons: Yes, No, and Cancel.
"Ok" (and default) MB_OK one pushbutton: OK
text text in box
default which of the above buttons is the default (1, 2, 3). Default default is 1.
title text in window title bar
icon
"Exclamation" MB_ICONEXCLAMATION An exclamation-point
"Information" MB_ICONINFORMATION An "i" in a circle
"Question" MB_ICONQUESTION A question-mark
"Stop" MB_ICONSTOP A stop-sign
The message box is forced into the foreground (MB_SETFOREGROUND is set).

Clicking a button will jump to the command with the label specified by the corresponding 'goto label' parameter below, if one is specified:
Button 'goto label' parameter default action if no 'goto' parameter
ABORT abort terminate the XBatch program
CANCEL cancel terminate the XBatch program
IGNORE ignore next command in sequence
NO no terminate the XBatch program
OK ok next command in sequence
RETRY retry repeat this command
YES yes next command in sequence


The Exist, NotExist, Version, and OSVsn commands may also contain the above parameters parameter, which are processed conditionally in the same way.

Examples

Usually the controlling XML file is generated automatically.
All the installation files on this site use XBatch.
- For the generic installation XML file creation, see XInst.js.

Compilation

XBatch is an MSDEV project, compiled using Microsoft Visual C++ vsn 6. The project file is XBatch.dsw.
The files generated by MSDEV are listed in ReadMe.txt.
- Of these, the main code is in file XBatch.cpp.