MMAPG - Installing a Program Using MINSTALL
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
This section describes the procedures for preparing control files for installing a multimedia application using the multimedia installation program (MINSTALL).
The MINSTALL program utilizes features provided by the OS/2 multimedia installation engine, such as creating workplace shell objects and changing the CONFIG.SYS file, providing a consistent installation process.
Note: For installation requirements when writing a subsystem, refer to the OS/2 Multimedia Subsystem Programming Guide.
Installation Overview
The MINSTALL program (MINSTALL.EXE) requires specific file information to install each program. This file information is provided by the master control file CONTROL.SCR.
The master control file, CONTROL.SCR, tells the installation program what to install, where to install it, how to display it to the user, and what system files need to be updated. CONTROL.SCR uses keywords to specify these instructions to MINSTALL. (See Master Control File.)
The following important keywords used in CONTROL.SCR specify subsequent control files that list the installation files, create necessary entries in the initialization file, and add appropriate lines in the CONFIG.SYS file:
- The keyword FILELIST specifies the name of the file list control file, which lists all the files in the installation package. (See File List Control File.)
- The keyword SSINICH identifies a control file that is used to define folders and programs.
- The keyword SSCONFIGCH identifies a control file that contains all the changes to be made to the CONFIG.SYS file for a particular installable item or subsystem.
For each installation, an error log called MINSTALL.LOG is created. If a problem occurs during installation, the problem is recorded in the error log and might also be displayed on the screen. You can read the log for more information about the error.
Master Control File
The master control file, CONTROL.SCR, contains information about each installable feature. It identifies specific file information that MINSTALL requires to install the requested features. This control file must be named CONTROL.SCR and must reside on the first media unit (diskette or CD) of the installation package.
During installation, if any errors are detected in the master control file, the main installation selection window will be empty and the errors will be logged in the error log MINSTALL.LOG. You can access this file for information about the errors.
The CONTROL.SCR file consists of a header section and a subsystem definition section. The header section comes first and provides general information for the installation procedure. The subsystem definition section comes next and provides information about the features in the installation package.
CONTROL.SCR Header
The header section of the CONTROL.SCR file contains the following information:
- Name of the installation package
- Code page used when creating the file
- Name of the file list control file
- Number of features in the installation package
- Number of media units required for installation
- Names of the media units required for installation
- Source and destination directory names (optional)
The following is an example of the CONTROL.SCR header located in the \TOOLKIT\SAMPLES\MM\SHORTCF subdirectory.
package='IBM Multimedia Presentation Manager Toolkit/2'
codepage=437
filelist='filelist.tk2'
groupcount=2
munitcount=1
medianame='IBM Multimedia Presentation Manager Toolkit/2 Installation
Diskette 1'
sourcedir = '\\' = 4
sourcedir = '\\MCISTRNG\\' = 11
destindir = '\\MMOS2\\' = 0
destindir = '\\MMOS2\\INSTALL\\' = 4
destindir = '\\MMOS2\\MMTOOLKT\\SAMPLES\\MCISTRNG\\' = 11
A larger and more complex example of installing multiple items using MINSTALL is located in the \TOOLKIT\SAMPLES\MM\CF subdirectory.
The following table describes the keywords used in the CONTROL.SCR header.
| Keyword | Description |
|---|---|
| PACKAGE | This required keyword specifies the name of the installation package in the form of a quoted string. For example: PACKAGE='IBM Multimedia Presentation Manager Toolkit/2' |
| CODEPAGE | This required keyword specifies the code page that the file was created under. For example: CODEPAGE = 437 |
| FILELIST | This required keyword specifies the name of the file list control file. This control file contains a list of files that make up each subsystem, identifies on which media units they reside in the installation package, and specifies the destination to which they will be copied. For example: FILELIST = 'FILELIST.TK2' |
| GROUPCOUNT | This required keyword specifies the number of subsystems in the installation package. All groups are counted, including group 0 (if present). For example: GROUPCOUNT = 2 |
| MUNITCOUNT | This required keyword specifies the number of media units (diskettes, CDs) that will be used if all features are installed. This number must be greater than 0. This is the number of diskettes or CDs on which the installation package resides. For example: MUNITCOUNT = 1 |
| MEDIANAME | This required keyword specifies a unique media name, which is a character string on the diskette or CD label. For each media unit, this keyword must be repeated once, in the form of a quoted string. This information is used during installation to prompt the user to insert a diskette or CD when needed. For example: MEDIANAME = 'IBM Multimedia Presentation Manager Toolkit/2 Installation Diskette 1' |
| SOURCEDIR | This optional keyword specifies the name of a source directory and its associated number. This keyword can be repeated and is specified by a quoted string followed by an equal sign (=) and a number. The number is used to identify the particular directory in later scripts. This can be NULL, in which case two default backslash characters (\\) are used with an encoding of 0. The path must be surrounded by path separators. For example: SOURCEDIR='\\LIB\\' = 1 |
| DESTINDIR | This optional keyword specifies the destination directory and its encodings. This keyword can be repeated and can be NULL, in which case the default is the \MMOS2 subdirectory. The path must be surrounded by path separators and any directory that does not exist will be created. For example: DESTINDIR = '\\MMOS2\\' = 0 |
Observe the following guidelines when you create or change a CONTROL.SCR header:
- You must place the keywords MUNITCOUNT and MEDIANAME so that MUNITCOUNT comes directly before MEDIANAME. The order of the other keywords is not significant.
- The destination directory (DESTINDIR) must have a unique number.
- A subsystem group can be spread across several media units. It does not have to reside on one media unit.
- A subsystem can define any directory. MINSTALL will create any subdirectories defined with the DESTINDIR keyword that do not exist.
- If you move the installation package files to media of a different size, the number of media units ( MEDIACOUNT) might change.
- You may use comments in the header section in the form of blank lines or text enclosed with '/* and */'. You may not use nested comments.
- You may use blank spaces around the equal sign; blank spaces are ignored.
- If you want to use a double quotation mark or a backslash in a string, you must precede it with the escape character (\).
- You may use the escape sequence \n (new line).
CONTROL.SCR Subsystem Definition
The subsystem definition section of the CONTROL.SCR file follows the header section and contains the definitions for all the installable items in the installation package. A block of information must be included for each subsystem.
The subsystem definition section contains the following information:
- The group or item number
- The item name
- The version of the item
- The size of all the files for the item installation
- The names of the control files that change the MMPM2.INI and CONFIG.SYS files
- The names of installation DLL files and entry points
The following is an example of a CONTROL.SCR subsystem definition.
ssgroup=0 /* base group */ sssize=41 ssname='mmbase' ssversion='1.0.9' ssinich='TLKBASE.SCR' /* - 11 = mcistrng */ ssgroup=11 ssname='Media Control Interface String Test' ssversion='1.0.9' sssize=200 ssinich='TLKSTRN.SCR' ssicon='mcistrng.ico'
The CONTROL.SCR subsystem definition consists of the following keywords.
| Keyword | Description |
|---|---|
| SSGROUP | This required keyword specifies the group or item number. This marks the beginning of a group for this item and assigns it a number. Each item must have a unique number from 0-49 within the package; however, the same number can be used with different installation packages. The groups are displayed in the installation main selection window in ascending order by group number. For example: SSGROUP = 11 |
| SSNAME | This required keyword specifies the item name, which names the current group as an ASCII string. This keyword is case sensitive and takes the form of a quoted string. The name may include special characters and may be translated. The name is displayed in the main installation selection window. For example: SSNAME = 'CD Audio' |
| SSVERSION | This required keyword specifies the version of the component in the form of a quoted string. This string must be in the format dd.dd.dd (where dd represents digits). Any version not specified in this format will be converted to that format. All string items that are not digits or periods will be converted to zeros. Any periods after the second period will be converted to zeros. For example: SSVERSION = '1.1.0' |
| SSIZE | This required keyword specifies the total size of all the files in the item. The size denotes the number of bytes in thousands (500 = 500KB). This number is used to help determine if there is enough disk space to support the installation. If you do not know the correct size of a item, overstate its size. For example: SSIZE = 1024 |
| SSINICH | This optional keyword specifies the name of the file that contains the changes to the MMPM2.INI file. If this statement is missing, there are no changes to the MMPM2.INI file. For example: SSINICH = 'ACPAINI.CH' |
| SSCONFIGCH | This optional keyword specifies the name of the file that contains the changes to the CONFIG.SYS file. If this statement is missing, there are no changes to the CONFIG.SYS file. For example: SSCONFIGCH = 'ACPACON.CH' |
| SSCOREQS | This optional keyword specifies a list of corequisites needed for this item to run. It also specifies what other components the current components depend on. These other components must be installed for the current component to function. (If this statement is missing, there are no corequisites.) The corequisite is identified by its group number. Corequisite groups should point to each other only if they require each other. It is possible to have subsystem A list subsystem B as a corequisite and subsystem B have no corequisites. If the user selects a subsystem with a corequisite, but does not select all corequisites, the user is notified before the installation starts. This entry can be repeated as necessary. For example: SSCOREQS = 1 |
| SSICON | This optional keyword names the icon file for this component that is to be displayed in the main installation selection window. The icon file to be displayed in the selection window must reside on the first installation media unit. If this statement is missing, a default icon is used. For example: SSICON = 'ACPA.ICO' |
| SSDLL | This optional keyword names a DLL file that is to be run during the installation process. The DLL referenced will be run after all files are copied to the destination, but before any script processing is performed. If this keyword is present, the SSDLLENTRY keyword must also be present. For example: SSDLL='MY.DLL' |
| SSDLLENTRY | This optional keyword specifies the name of the entry point into SSDLL in the form of a quoted string. If this keyword is present, the SSDLL keyword must also be present. For example: SSDLLENTRY='MyEntry' |
| SSTERMDLL | This optional keyword names a DLL file that is to be run during the installation process. The DLL referenced will be run after all files are copied to the destination and after all script processing is done. The purpose of this keyword is to allow for processing to occur on a fully configured multimedia system. If this keyword is present, the SSTERMDLLENTRY keyword must also be present. For example: SSTERMDLL='MYTERM.DLL' |
| SSTERMDLLENTRY | This optional keyword specifies the name of the entry point into SSTERMDLL in the form of a quoted string. If this keyword is present, the SSTERMDLL keyword must also be present. For example: SSTERMDLLENTRY='MyTermEntry' |
| SSELECT | This optional keyword determines the preselection of items for installation. Five values are supported: 'ALWAYS' - This value specifies that the group will always be installed. It is the only valid value for Group 0. Groups with this value will not be displayed in the installation selection window. This is the default. 'REQUIRED' - This value specifies that the group will be preselected for installation. If the group had been previously installed, it cannot be unselected by the user if this installation package is newer than the installed version. If the group has not been previously installed, it can be unselected by the user. 'VERSION' - This value specifies that the group will be preselected only if it was previously installed and this installation package is newer than the installed version. However, it can be unselected by the user. 'YES' - This value specifies that the group will be preselected whether or not it was previously installed. It can be unselected by the user. 'NO' - This value specifies that the group is never preselected but can be selected by the user. 'BASENEWER' - This value specifies that files belonging to this group will only be copied if the user's machine has no package installed or if the package installed is older than the current package. 'ONLYNEWER' - This value specifies that user will not be able to install an older version of a package on top of a newer version. Files belonging to this group will only be copied if the user has an older version (or the same version) installed. If no version is installed or if the version installed is higher than the one in the package, no files will be copied. |
Observe the following guidelines when you create or change a CONTROL.SCR subsystem definition:
- The SSGROUP keyword must be the first statement in the information block.
- An item may reside on different media.
- Each statement in the information block must have a value.
- You may use comments in the header section in the form of blank lines or text enclosed with '/* and */'. You may not use nested comments.
- You may use blank spaces around the equal sign; blank spaces are ignored.
- If you want to use a double quotation mark or a backslash in a string, you must precede it with the escape character (\).
- You may use the escape sequence \n (new line).
File List Control File
The master control file, CONTROL.SCR, specifies a FILELIST keyword which identifies the name of a file list control file that lists all the installable files in the installation package. The file list control file also contains the following additional information:
- The name of the file
- The number of the media unit where the file is stored
- The destination directory where the file will be copied
- The group or feature the file is identified with
The following is an example of the file list control file (FILELIST.TK2) located in the \TOOLKIT\SAMPLES\MM\SHORTCF subdirectory. The first nonblank, noncomment line is a count of the number of files (or file name lines) in the file.
/***********************************************************************/
/* This file contains install information. Comments are delimited */
/* as these comments are. Blank lines are ignored. Non-blank lines */
/* will be parsed and extraneous characters will cause errors. First */
/* non-comment line must be the total number of files to be installed. */
/***********************************************************************/
/* all files on the install disk(s) are listed below. Other */
/* information is also given, as follows: */
/* */
/* Disk# - The number of the disk on which the file resides. */
/* (Ignored if installing from CD-ROM). These are sorted */
/* from 0 to the number of disks, ascending. */
/* */
/* Group# - The logical group to which the file belongs. Group */
/* starts at 0. */
/* */
/* Dest# - The destination subdirectory into which the file will be */
/* copied. Dest# starts at 0. */
/* */
/* Source #- The installation disk(s) subdirectory where the file */
/* resides. */
/* */
/* FileName - The base filename. */
/* */
/*sourcedir='\\' = 4 */
/*sourcedir='\\MCISTRNG\\' = 11 */
/* */
/* destindir='\\MMOS2\\' = 0 */
/* destindir='\\MMOS2\\INSTALL\\' = 4 */
/* destindir='\\MMOS2\\MMTOOLKT\\SAMPLES\\MCISTRNG\\' = 11 */
/* */
/* groups */
/* 0 = Base */
/* - 11 = MCI String Test */
/* */
/***********************************************************************/
/* Total number of entries is 20. This must be the first parameter other*/
/*than comments*/
/***********************************************************************/
20
/*It is a good practice to make groups and list the amount of files in
/*them (9 files)*/
/*A comment can not be the last line in a filelist.*/
/* mmtoolkt\samples\cf 9 41K */
0 0 11 4 'CONTROL.SCR'
0 0 11 4 'FILELIST.TK2'
0 0 11 4 'TLKSTRN.SCR'
0 0 11 4 'TLKBASE.SCR'
0 0 4 4 'TLKSTRN.SCR'
0 0 4 4 'TLKBASE.SCR'
0 0 4 4 'MCISTRNG.PNG'
0 0 4 4 'MMTOOLKT.PNG'
0 0 11 4 'TOOLKIT.CH'
/* 11 files */
/* mmtoolkt\samples\mcistrng 11 197K */
0 11 11 11 'mcistrng.c'
0 11 11 11 'mcistrng.h'
0 11 11 11 'mcistrng.rc'
0 11 11 11 'mcistrng.dlg'
0 11 11 11 'mcistrng.def'
0 11 11 11 'makefile'
0 11 11 11 'UMB.DAT'
0 11 11 11 'mcistrng.exe'
0 11 11 11 'mcistrng.hlp'
0 11 11 11 'mcistrng.ipf'
0 11 11 11 'mcistrng.png'
The following table describes the columns in the file list control file.
| Column | Description |
|---|---|
| Media# | Specifies the number of the media unit (diskette or CD) where the file is stored. The units are numbered starting from 0. This number will be used for all installation media except for the hard disk. The Media# column must be sorted in ascending order. A media unit does not have to be filled (there can be unused space on any numbered unit). |
| Group or subsystem# | Specifies the group to which the file belongs. The group or item number must be a positive integer, with numbering starting at 0 (the groups are defined in CONTROL.SCR by the SSGROUP keyword). This number is used to determine which files belong to a item selected for installation. |
| Destination# | Specifies the destination subdirectory where the file will be copied. The destination number is defined in the CONTROL.SCR file by the DESTINDIR keyword. This field must always be a defined number (for example, 14 for the \MMOS2\DLL path). If you specify a DESTINDIR statement in the master control file, you only have to specify the corresponding group number (for example, 1). |
| Source# | Specifies the path name of the source file. The source number is defined in the CONTROL.SCR file by the SOURCEDIR keyword. This field must always be defined with a number (for example, 1 for the \LIB path). |
| File name | Specifies the base file name, which must be in double quotes. For example, 'MINSTALL.EXE'. |
Change Control Files
Change control files are script files that make changes to the CONFIG.SYS file and INI files. The master control file, CONTROL.SCR, identifies the change control files when you specify the SSINICH and SSCONFIGCH keywords.
Supported Macros
Macros can be used in the change control files. Macros can also be used in the master control file. When a supported macro is used, drives and paths do not have to be identified until the time of installation. At installation, macros can perform the following:
- Replace the full destination path of the file
- Replace the installation target drive letter
- Replace the default destination drive and path as defined in CONTROL.SCR
- Replace the startup (boot) drive letter of the operating system
- Delete specified files
The following table describes the supported macros. Refer to the TLKSTRN.SCR file in the \TOOLKIT\SAMPLES\MM\SHORTCF subdirectory for an example.
Macro Description
destindir = '$(DELETE)\\path\\' = number
The $(DELETE) macro can only be used with the DESTINDIR keyword in the master control file. The relative number is listed in the file list control file. Every file that has this number will be deleted from the user's machine.
$(DEST)filename $(DEST) is replaced with the full destination path of the file. For example:
$(DEST)CLOCK.EXE
becomes
D:\MMOS2\MMTOOLKT\SAMPLES\CLOCK\CLOCK.EXE
$(DRIVE) $(DRIVE) is replaced by the installation target drive letter. (Do not append a colon.) For example:
$(DRIVE)\MMOS2\TEST1.EXE
becomes
D:\MMOS2\TEST1.EXE
$(DIR)# # is the number of the destination directory as stated in the file CONTROL.SCR. The macro is replaced by the default drive and path defined in the CONTROL.SCR file for the specified DESTINDIR definition. For example:
$(DIR)4\MINSTALL.LOG
becomes
D:\MMOS2\INSTALL\MINSTALL.LOG
$(BOOT) Replaces the startup (boot) drive letter of the operating system. (Do not append a colon.) For example:
$(BOOT)\OS2\NEW.SYS
becomes
C:\OS2\NEW.SYS
where C: is the drive on which OS/2 is installed.
Note: Using multiple macros is supported.
INI Change Control Files
You can use an INI change control file to do the following:
- Define folders and add them to the system
- Define programs and add them to a folder
- Install subsystems such as media control drivers, stream handlers, and I/O procedures. (See the OS/2 Multimedia Subsystem Programming Guide for further details.)
The following WPObject structures call the OS/2 WinCreateObject function, which adds an icon and title to the desktop. This structure indirectly changes the OS2.INI file. See the OS/2 Presentation Manager Programming Reference for object class definitions and supported keywords for the object class you are creating.
Defining Folders
Use the following structure to define a folder. Refer to the TLKBASE.SCR file located in the \TOOLKIT\SAMPLES\MM\SHORTCF subdirectory for an example.
WPObject = ( WPClassName = 'WPFolder' WPTitle = 'title' WPSetupString = 'ICONFILE=$(DEST)icon;OBJECTID=<folderobjid>' WPLocation = '<parentfolderobjid>' WPFlags = 0 )
title Specifies the folder title to be displayed below the object. icon Specifies the name of the icon to displayed on the desktop. folderobjid Specifies the OS/2 unique object ID that is used to find this folder. This is used by the installation program to determine if this folder exists or not. It is also used in the WPLocation field of other WPObject definitions. parentfolderobjid Specifies the folder object ID of the folder in which this folder is to be placed. For example, '<WP_DESKTOP>' is the object ID for the Workplace Shell desktop folder. WPFlags = 0 Specifies creation control. These flags are also documented under WinCreateObject in the OS/2 Presentation Manager Programming Reference. Possible values include:
- 0 (CO_FAILIFEXISTS) - The folder is to be replaced if it exists, or added if it does not already exist.
- 1 (CO_REPLACEIFEXISTS) - The folder is to be replaced if it exists, or added if it does not already exist.
- 2 (CO_UPDATEIFEXISTS) - The folder is to be updated with the values supplied if it exists, or added using values supplied and defaults if it does not already exist.
In the following example, a folder called Multimedia Presentation Manager Toolkit/2 will be added to the desktop.
WPObject =
(
WPClassName = 'WPFolder'
WPTitle = 'Multimedia Presentation\nManager Toolkit/2'
WPSetupString = 'ICONFILE=$(DEST)MMTOOLKT.PNG;OBJECTID=<MMPMTLK>'
WPLocation = '<WP_DESKTOP>'
WPFlags = 2L
)
Defining Programs Use the following structure to define a program that is to be added to a folder. Refer to the TLKSTRN.SCR file located in the \TOOLKIT\SAMPLES\MM\SHORTCF subdirectory for an example.
WPObject =
(
WPClassName = 'WPProgram'
WPTitle = 'title'
WPSetupString = 'EXENAME=path file;STARTUPDIR=dir;PROGTYPE=PM;
ICONFILE=$(DEST)icon; [ASSOCTYPE=type;]
[ASSOCFILTER=filter;] OBJECTID=<pgmobjid>'
WPLocation = '<parentfolderobjid>'
WPFlags = 0
)
Note: The program setup information (WPSetupString) must be one line, not two as shown in the previous figure.
title Specifies the title to be displayed below the object in the parent folder. path Specifies a supported macro or the full path for the EXE file. icon Specifies the name of the icon to be displayed on the desktop. file Specifies the EXE file name. dir Specifies the full path of the startup directory or the macro $(DIR)# (where # is a defined destination directory in CONTROL.SCR). type Specifies one or more association types such as 'Waveform'. Multiple values are separated by commas. filter Specifies one or more association filter types such as '*.WAV'. Multiple values are separated by commas. pgmobjid Specifies the OS/2 unique object ID that is used to find this program. This is used by the installation program to determine if this program exists in the parent folder. It is not used in the WPLocation field of any WPObject definition. parentfolderobjid Specifies the folder object ID of the folder in which this program is to be placed. WPFlags = 0 Specifies that the program is to be added to the folder only if it does not already exist.