Welcome to the CatSetup 1.9 KittyScript Documentation!

By Steven Lawrance

 

Contents

The CatSetup.Inf File

Modes

Commands

Normal Mode

AskQuestion
AskUser
CatInf
DiskChange
EndScript
Exec
GetDrives
IfFile
IfNotFile
IniValue
Install
Jump
Message
ProgMan
Return
SetDir

Install Mode

Copy
Delete
EndMode
Expand
InstDel
NewDir
RmDir

ProgMan Mode

AddGroup
AddItem
DeleteGroup
DeleteItem
EndMode
ShowGroup

Examples

Internet Edition

 

The CatSetup.Inf File

The script in the CatSetup.Inf is executed by default when CatSetup is run. Other Inf files can be used, however, either by switching the current Inf file during execution or by specifying the Inf file to use as a parameter when running the setup program.

The format of a CatSetup Inf file consists of commands that are separated by line breaks and appear in the order in which they should execute. Program flow can be controlled with Jumps and Returns as well as conditional statements.

Basic format of a command:
Message("Welcome to CatSetup 1.9!", "Documentation", Y)

A command must appear on one and only one line. The parameters of a command are enclosed in parenthesis and can either be a string, a number, or a boolean value. Boolean values are represented with either a Y for "yes," a N for "no," an A for "ask user," or a V for "version check." The "ask user" and "version check" values can only be used in Copy and Expand. The "version check" value is new with CatSetup 1.9 and cannot be used with previous versions of CatSetup before 1.9. A string can be preceded by one of three variables, WIN, SYS, or DIR, to specify the Windows directory, the Windows System directory, or the current installation directory, respectively. These variables already end with backslashes for your convenience. String values can be of zero length by using "". If a variable is to be used without any need for string afterwards, an empty "" string must be used anyway. To use a variable in a string, simply state the variable name, a plus sign, and the string. Note that a space before or after the plus sign will cause an error.

Example of a variable:
Copy("catsetup.gif", DIR+"catsetup.gif", A)

In the example, the file named "catsetup.gif" will be copied to a file named "catsetup.gif" in the current install directory.

Example of a string:
Message(WIN+"", "Location of your Windows directory", Y)

All scripts must end with an EndScript command. Scripts may be exited early by calling the same command.

 

Modes

In CatSetup, there are three modes that enable certain types of commands. In the Install mode, file operations may take place. In the ProgMan mode, groups and icons can be manipulated. When the installer is not in either mode, then it is in the Normal mode. You can only be in one mode at a time. To enter the Install mode, simply use the Install command. When you are finished manipulating files, then use the EndMode command to end the current mode. Note that the EndMode command cannot be used to end the Normal mode; EndScript should be used to do that. Using the EndMode command restores the installer to the Normal mode. To enable the Program Manager commands, the ProgMan command should be used. When you are finished with the Program Manager commands, then use the EndMode command to return to the Normal mode.

Example of using a mode:
Message("In Normal mode", "Documentation", Y)
Install
Message("In Install mode", "Documentation", Y)
Copy("catsetup.gif", DIR+"catsetup.gif", A)
EndMode
Message("In Normal mode", "Documentation", Y)
EndScript
Message("Not in any mode", "Documentation", Y)

Note that the last command will never be executed nor even checked. The script had ended with the EndScript command, so you are free to put whatever you want to after the EndScript.

 

Commands

Normal Mode

These commands may be used in the Normal mode.

AskQuestion(QuestionString, TitleString, DefaultButtonBoolean, SoundBoolean)

Asks the user a Yes/No question with a dialog box. The TitleString will be used as the title of the dialog box. If you wish to play the sound for a question, then set the SoundBoolean to Y; otherwise, set it to N. The value of DefaultButtonBoolean determines which button, Yes or No, will be selected by default when the dialog box appears.

If the user pressed Yes, then the next command is executed. If the user pressed No, then the command after the next command is executed.

Example:
GetDrives("Documentation", "docs", Y)
AskQuestion("Install the Plus Pack?", "Documentation", Y, Y)
Jump("[Plus Pack]")
Message("Thank you for installing this program!", "Documentation", Y)
EndScript

[Plus Pack]
Install
Expand("pluspack.exe", DIR+"pluspack.exe", V)
EndMode
Return

AskUser(TitleString, QuestionString, Response1String, Response2String, Response1JumpString, Response2JumpString)

The user is asked a question of QuestionString and has the option of selecting Response1String or Reponse2String. Once the user selects an option and presses OK, the installer performs a Jump command based on the user's selection. If the user selected the first option, the installer performs the equivalent of Jump(Response1JumpString). If the user selected the other option, the equivalent of Jump(Response2JumpString) is executed. The TitleString is used as the title of the window.

Example of AskUser:
AskUser("Documentation", "Favorite Movie", "In && Out", "Plan 9 from Outer Space", "[In & Out]", "[Plan 9]")
Message("This is never executed", "Documentation", Y)

[In & Out]
Message("Everyone, he just meant that he's having a good day!", "Documentation", Y)
EndScript

[Plan 9]
Message("Atmospheric conditions in outer space often interfere with transmitting.", "Documentation", Y)
EndScript

CatInf(InfFileNameString)

Sets the current Inf file to the Inf file described by the InfFileNameString. The current Inf file is closed, the new one opened, and execution resumes from the beginning of the new Inf file with all the variables in tact.

DiskChange(DiskNameString, DiskFileString)

Automates disk changing by asking the user to insert the disk named DiskNameString. The installer checks for the presence of DiskFileString. If it exists, then the command returns. If not, the user is asked until the user exits or inserts the correct disk. Note that if you have multiple disks, the Inf file should be running off of the hard drive such as in a temporary copy. This is required because the Inf file is read with each command; it is not preloaded.

Example:
GetDrives("Documentation", "docs", Y)
DiskChange("Disk 1", "catsetup.gif")
Install
Copy("catsetup.gif", DIR+"catsetup.gif", A)
EndMode
DiskChange("Disk 2", "catsetup.htm")
Install
Copy("catsetup.htm", "DIR+"catsetup.htm", A)
EndMode
EndScript

The previous example assumes that the script is running off of a hard drive and not the disk. This can be done with the following example:

CatSetup.Inf:
GetDrives("Documentation", "docs", Y)
Install
Copy("part2.inf", DIR+"part2.inf", Y)
EndMode
CatInf(DIR+"part2.inf")
EndScript

The Part2.Inf file could consist of the first example without the GetDrives command (the user was already asked for the drive!).

EndScript

Causes the installer to stop executing commands and finish the installation. If the InstDel command was issued during an Install mode, the original Inf file is deleted in addition to the installer, if possible.

Exec(ProgramFileNameString, ParameterString)

The program file name in ProgramFileNameString is executed with the parameters set to ParameterString. A separate process is created and executed independently of the installer. This means that when this command returns, the program that you had just executed may or may not be running. At present, CatSetup has no command for checking the status of the program you had executed.

GetDrives(ProgramNameString, DefaultDirectoryString, CreateDirectoryBoolean)

The user is asked for the drive and directory to install to. The drive is determined by the drive that the installer is running from. If that drive is a floppy drive, then the first hard drive letter is used. The directory in DefaultDirectoryString is used as the default value in the directory edit control. Note that this value cannot exceed 8 characters due to limitations on filenames within 16-bit programs. When CreateDirectoryBoolean is Y, the directory is created when the user continues if the directory does not exist. If CreateDirectoryBoolean is N, then the directory must exist before the user can continue. The ProgramNameString is used in the dialog box as the name of the program that is currently installing. This can be any string.

Example:
GetDrives("Documentation", "docs", Y)
Install
Copy("catsetup.gif", DIR+"catsetup.gif", A)
EndMode
EndScript

IfFile(FileNameString)

If the file named FileNameString exists, then the next command is executed. Otherwise, the command after the next command is executed.

IfNotFile(FileNameString)

If the file named FileNameString does not exist, then the next command is executed. Otherwise, the command after the next command is executed.

IniValue(IniFileNameString, SectionString, EntryString, ValueString)

Sets a value in an .ini file. This command is new to CatSetup 1.9, meaning that it will not work with previous versions. The value of ValueString is written to the entry named EntryString within the SectionString section of the .ini file named by IniFileNameString. If IniFileNameString does not specify a directory for the .ini file, the Windows directory is used by default.

Example (sample.inf file):
[Documentation]
InstallDirectory=c:\docs\
WelcomeMsg=Welcome to the documentation!

[Associations]
.inf=c:\docs\catsetup.exe

The .ini file above can be produced with the following script:
GetDrives("Documentation", "docs", Y)
IniValue("sample.inf", "Documentation", "InstallDirectory", DIR+"")
IniValue("sample.inf", "Documentation", "WelcomeMsg", "Welcome to the documentation!")
IniValue("sample.inf", "Associations", ".inf", DIR+"catsetup.exe")

Install

Enters the Install mode. This enables file commands. The files referenced within the following Install .. EndMode block are checked for existence and file size. The combined size is compared to the free space of the current installation directory. If there is enough space, the installer enters the Install mode and execution resumes with the file commands enabled.

Jump(LabelName)

Jump to the line in the current Inf file whose line's contents consist of LabelName. Execution resumes at the line after that line. Because LabelName consists of the entire line to jump to, the [ and ] brackets are included in the LabelName. Note that labels in brackets cannot be executed; if labels are used, then program flow must be controlled by Jump commands to avoid accidental execution of the label, which would result in an error.

Example of a jump:
Message("About to jump", "Documentation", Y)
Jump("[Place to Go 1]")
Jump("[Place to Go 2]")
[Place to Go 1]
Message("Jumped! About to return", "Documentation", Y)
Return

blah blah blah blah

[Place to Go 2]
Message("About to exit.. Have a great day!", "Documentation", Y)
EndScript

Note that if the Jump("[Place to Go 2]") was not a jump, then the line containing [Place to Go 1] would be executed (the [Place to Go 1] block ends with a Return, meaning that the next command to be executed is the one that follows the last Jump command that was executed). Because it is not a valid command, an error would be generated. Careful attention must be paid to program flow so that you are sure that only commands are executed in every possible case.

Message(MessageText, TitleString, SoundBoolean)

Informs the user with a dialog box. The TitleString will be used as the title of the dialog box. If you wish to play the sound for a question, then set the SoundBoolean to Y; otherwise, set it to N.

ProgMan

Enters the ProgMan mode. At this time, a DDE connection with Program Manager is established. Any errors are reported and stop the installer.

Return

If you had executed a Jump, then you have the option of returning to the point of the last Jump and executing the command after that Jump command. For an example, see the documentation for the Jump command.

SetDir(DirectoryNameString)

Sets the directory variable to the DirectoryNameString. This can be useful for installations that always install to a fixed directory and don't require GetDrives to ask the user for a directory.

Install Mode

The commands in the Normal mode, except for CatInf, GetDrives, Install, ProgMan, EndScript, IniValue, and Exec, can be used in addition to the following in the Install mode.

Copy(SourceFileNameString, DestinationFileNameString, OverwriteBoolean)

Copies the file named SourceFileNameString to DestinationFileNameString. If the destination file already exists, then OverwriteBoolean is used to determine the course of action. When set to Y, the file is overwritten. When set to N, the file is not overwritten. When set to A, the user is asked whether to overwrite the file or not (the user is informed about whether the existing file is newer or not). When set to V, the existing file is overwritten if the source file has a newer version (if the existing file is older, then the user is asked if the file should be overwritten). Note that if a file does not contain version information (such as any file that is not an EXE or DLL), then no version checking takes place. Version checking is new to CatSetup 1.9 and did not exist in versions prior to 1.9. If the file was compressed, no decompression takes place.

Delete(FileNameString)

Deletes the file named FileNameString. This is useful during uninstallation procedures.

EndMode

Ends the Install mode and returns to the Normal mode.

Expand(SourceFileNameString, DestinationFileNameString, OverwriteBoolean)

Expands the file named SourceFileNameString to DestinationFileNameString. If the destination file already exists, then OverwriteBoolean is used to determine the course of action. When set to Y, the file is overwritten. When set to N, the file is not overwritten. When set to A, the user is asked whether to overwrite the file or not (the user is informed about whether the existing file is newer or not). When set to V, the existing file is overwritten if the source file has a newer version (if the existing file is older, then the user is asked if the file should be overwritten). If the file was compressed, file decompression takes place using the appropriate decompressor (currently, only LZExpand is supported). Note that if a file does not contain version information (such as any file that is not an EXE or DLL), then no version checking takes place. Version checking is new to CatSetup 1.9 and did not exist in versions prior to 1.9. If the file was not compressed, Expand behaves just like Copy; it copies the file.

InstDel

Flags the installer to delete the installer and the original Inf file as soon as the installer exits. Because the removal of the installer might hinder other programs that use CatSetup from uninstalling, the use of this command is not recommended.

NewDir(DirectoryName)

Creates a new directory named DirectoryName. This is useful when creating directory hierarchies in installations.

RmDir(DirectoryName)

Removes the directory named DirectoryName. If that directory is not empty, then it is not removed and a warning is presented (program flow is not interrupted; execution continues normally).

ProgMan Mode

The following commands can be used in the ProgMan mode (none of the commands from the Normal mode may be used in the ProgMan mode).

AddGroup(GroupNameString)

A group named GroupNameString is created and automatically brought into view for adding icons.

AddItem(ItemPathString, ItemRunPathString, ItemNameString, ItemIconFileNameString, ItemIconIndexNumber)

An item is added to the currently open group. The ItemPathString is the command that is used to execute the item. The ItemRunPathString is the path of the directory that the program will use as its running directory (the Open and Save As dialog boxes in the program associated with this item generally use this directory). Below the item's icon, the ItemNameString is used as the name of the item. The ItemIconFileNameString tells the Program Manager which file to extract the icon from. This can generally be an .ico, .exe, or .dll file. Use the ItemIconIndexNumber to specify the zero-based icon index to use. If you want the first icon in the icon resource you specified, then use zero. In the case of .ico files, ItemIconIndexNumber must be zero because .ico files can generally only hold one icon. Note that the ItemIconFileNameString parameter can be an empty string to let Windows figure out which icon to used based on the extension type.

Example:
ProgMan
AddGroup("CatSetup 1.9 Documentation")
AddItem(DIR+"catsetup.htm", DIR+"", "Documentation in HTML", "", 0)
AddItem(DIR+"catsetup.exe", DIR+"", "CatSetup 1.9 Program", DIR+"catsetup.exe", 0)
EndMode
EndScript

DeleteGroup(GroupNameString)

The group named GroupNameString is deleted.

DeleteItem(ItemNameString)

The item in the currently visible group named ItemNameString is deleted.

EndMode

Ends the ProgMan mode and returns to the Normal mode.

ShowGroup(GroupNameString)

Brings the Program Manager group named GroupNameString into view. This can be useful for deleting icons; bringing the group into view is a required step in that process.

 

Examples

AriesType! Installation Script

In the following script, the AriesType! program is installed, an external program is invoked to set the configuration files, and the icons are created. Note that AriesType! 2.2 is a MS-DOS program and cannot have versions compared.

CatSetup.Inf

GetDrives("AriesType! 2.2", "Type!", Y)
Install
NewDir(DIR+"shardrv")
NewDir(DIR+"temp")
Expand("aries.ba_", DIR+"aries.bat", Y)
Expand("artype.co_", DIR+"artype.com", Y)
Expand("intro.ba_", DIR+"intro.bat", Y)
Expand("large.co_", DIR+"large.com", Y)
Expand("scr1.co_", DIR+"scr1.com", Y)
Expand("scr2.co_", DIR+"scr2.com", Y)
Expand("scr3.co_", DIR+"scr3.com", Y)
Expand("scr4.co_", DIR+"scr4.com", Y)
Expand("scr5.co_", DIR+"scr5.com", Y)
Expand("small.co_", DIR+"small.com", Y)
Expand("student.ex_", DIR+"student.exe", Y)
Expand("teacher.ex_", DIR+"teacher.exe", Y)
Expand("teachers.ex_", DIR+"teachers.exe", Y)
Expand("typecfg.ex_", DIR+"typecfg.exe", Y)
Expand("typeinst.ex_", DIR+"typeinst.exe", Y)
Expand("typeutil.ex_", DIR+"typeutil.exe", Y)
Expand("a1.in_", DIR+"shardrv\1.inf", Y)
Expand("a1.ty_", DIR+"shardrv\1.typ", Y)
Expand("compute1.ls_", DIR+"shardrv\compute1.lsn", Y)
Expand("computer.ls_", DIR+"shardrv\computer.lsn", Y)
Expand("fox.ls_", DIR+"shardrv\fox.lsn", Y)
Expand("lanstype.ls_", DIR+"shardrv\lanstype.lsn", Y)
Expand("lesson.ls_", DIR+"shardrv\lesson.lst", Y)
Expand("letters._", DIR+"shardrv\letters!", Y)
Expand("letters.de_", DIR+"shardrv\letters!.del", Y)
Expand("sample.ls_", DIR+"shardrv\sample.lsn", Y)
Expand("slw286.ls_", DIR+"shardrv\slw286.lsn", Y)
Expand("student.in_", DIR+"shardrv\student.inf", Y)
Expand("sysop.in_", DIR+"shardrv\sysop.inf", Y)
Expand("today.ls_", DIR+"shardrv\today.lsn", Y)
Expand("type.ls_", DIR+"shardrv\type!.lsn", Y)
Expand("type.ic_", DIR+"type!.ico", Y)
Copy("uninstal.inf", WIN+"artype22.inf", Y)
Expand("catsetup.ex_", WIN+"catsetup.exe", V)
EndMode
Exec(DIR+"typeinst.exe", DIR+"")
ProgMan
AddGroup("AriesType! 2.2")
AddItem(DIR+"typeutil.exe", DIR+"", "Main Menu", DIR+"type!.ico", 0)
AddItem(DIR+"student.exe", DIR+"", "Student Menu", DIR+"type!.ico", 0)
AddItem(DIR+"teacher.exe", DIR+"", "Teacher Menu", DIR+"type!.ico", 0)
AddItem(DIR+"teachers.exe", DIR+"", "Graphical Teacher Menu", DIR+"type!.ico", 0)
AddItem(DIR+"typecfg.exe", DIR+"", "Sysop Menu", DIR+"type!.ico", 0)
AddItem(DIR+"intro.bat", DIR+"", "Program Credits", DIR+"type!.ico", 0)
AddItem(WIN+"catsetup.exe artype22.inf", DIR+"", "Uninstall AriesType! 2.2", WIN+"catsetup.exe", 0)
EndMode
Exec(DIR+"intro.bat", DIR+"")
Message("Enjoy AriesType! 2.2! When asked for the Sysop Password, simply press [Enter] without typing in anything.", "Installation Complete!", N)
EndScript

The following script is run when the user clicks on "Uninstall AriesType! 2.2" from the "AriesType! 2.2" Program Manager group:

Uninstal.Inf

AskQuestion("Are you sure you want to uninstall AriesType?", "Uninstall Warning", N, Y)
Jump("[CheckExist]")
EndScript

[CheckExist]
IfNotFile("typecfg.exe")
Jump("[AskForDrive]")
Jump("[UnInstall]")

[AskForDrive]
GetDrives("AriesType! 2.2", "Type!", N)
Jump("[UnInstall]")

[UnInstall]
Install
Delete(DIR+"aries.bat")
Delete(DIR+"artype.com")
Delete(DIR+"intro.bat")
Delete(DIR+"large.com")
Delete(DIR+"scr1.com")
Delete(DIR+"scr2.com")
Delete(DIR+"scr3.com")
Delete(DIR+"scr4.com")
Delete(DIR+"scr5.com")
Delete(DIR+"small.com")
Delete(DIR+"student.exe")
Delete(DIR+"teacher.exe")
Delete(DIR+"teachers.exe")
Delete(DIR+"typecfg.exe")
Delete(DIR+"typeinst.exe")
Delete(DIR+"typeutil.exe")
Delete(DIR+"shardrv\1.inf")
Delete(DIR+"shardrv\1.typ")
Delete(DIR+"shardrv\compute1.lsn")
Delete(DIR+"shardrv\computer.lsn")
Delete(DIR+"shardrv\fox.lsn")
Delete(DIR+"shardrv\lanstype.lsn")
Delete(DIR+"shardrv\lesson.lst")
Delete(DIR+"shardrv\letters!")
Delete(DIR+"shardrv\letters!.del")
Delete(DIR+"shardrv\sample.lsn")
Delete(DIR+"shardrv\slw286.lsn")
Delete(DIR+"shardrv\student.inf")
Delete(DIR+"shardrv\sysop.inf")
Delete(DIR+"shardrv\today.lsn")
Delete(DIR+"shardrv\type!.lsn")
Delete(DIR+"type!.ico")
IfFile(DIR+"type!.cfg")
Delete(DIR+"type!.cfg")
IfFile(DIR+"student.cfg")
Delete(DIR+"student.cfg")
IfFile(DIR+"teacher.cfg")
Delete(DIR+"teacher.cfg")
RmDir(DIR+"temp")
RmDir(DIR+"shardrv")
RmDir(DIR+"")
EndMode
ProgMan
ShowGroup("AriesType! 2.2")
DeleteItem("Main Menu")
DeleteItem("Student Menu")
DeleteItem("Teacher Menu")
DeleteItem("Graphical Teacher Menu")
DeleteItem("Sysop Menu")
DeleteItem("Program Credits")
DeleteItem("Uninstall AriesType! 2.2")
DeleteGroup("AriesType! 2.2")
EndMode
Message("AriesType! 2.2 has been removed.", "Uninstall Completed", Y)
EndScript

In the uninstall example, the script checks to see if the current directory is the program directory. The install script told Program Manager to use the AriesType! program directory as the program run directory for CatSetup, so when the user opens that icon, the AriesType! program directory is automatically the current directory and thus the initial value in the DIR variable. There might be exceptions, such as if the user removed the program run directory from the icon's properties. In that case, the script senses that a program file does not exist in the current directory and thus asks the user for the directory. If the user can provide it, then that directory is used and the program is uninstalled.

 

Internet Edition

If you're wondering what is so special about the "Internet Edition" of CatSetup, then you've come to the right place. Instead of requiring your users to download a .zip file containing the installation and then run the setup.exe, you can give your users a single .exe file that they run to install the program. Versions of CatSetup since 1.7 support files within the installer's .exe file as RCDATA. To add RCDATA, you'll need a resource editor that can modify the resources of .exe files such as Borland's Resource Workshop. Periods in filenames must be saved as the _ underscore in the resource name for that file. Files cannot start with an underscore or a number; it must be a letter. All letters in the resource name must be upper-case. In the resource properties, enable moveable and discardable.

Examples:
catsetup.htm is saved as CATSETUP_HTM in the resources
my_file.txt is saved as MY_FILE_TXT in the resources
1doc.txt cannot be saved in the resources with that name
onedoc.txt can be used instead, because it is saved as ONEDOC_TXT

When a file command such as Copy("catsetup.gif", DIR+"catsetup.gif", A) is executed, the installer searches for a resource named CATSETUP_GIF. If no such resource was found, then the file is opened. This procedure prevents the installer from accidentally using an external file that happened to have the same name; the embedded files have priority.

Once an embedded file is accessed, it is extracted and placed into a temporary directory for subsequent accesses. Once the installer exits, any extracted files in the temporary directory are deleted.

In version 1.9, the original file dates and times are lost when using embedded files (the installation date and time is used instead).

When embedding files, it is suggested that you use compression on all of your files. When the files are extracted from the .exe, some whitespace might exist at the end of the file due to the boundary alignments of resources. With compression, the decompression will ensure that the original file will be produced without the whitespace at the end.

Make sure that you have thoroughly tested your installer scripts before embedding them into an .exe. This can save a lot of time. Once you have it working properly, then the chances that it will work in an embedded .exe file are quite high. If you do not have a resource editor, then please feel free to e-mail Steven Lawrance at slawrance@technologist.com with a .zip file of the installation set. I can quickly create an embedded .exe and send it back.