Clarion Third Party Association

Clarion 3rd Party Association Toolkit
Version 2.12 - 1 August 2003

C3PA Toolkit
The C3PA Toolkit is supplied, free of charge, to C3PA members. It is primarily designed to assist with the tasks which are laid down in the Standards, and which are not easily accomplished with Install languages.

Acknowledgements
The following programmers have contributed to this utility;

Phillip Carroll (Paragon Design and Development)
Dominick Galucci (Tinman Development Corporation)
Pete Halstead (NextAge Consulting)
Richard Rogers (The Sylkie Enterprise)
Robert Rogers (Sylvan Computing)
Bruce Johnson (CapeSoft)
Paul Bremer (CapeSoft)

Accessories Install Utility (AccIni)
This utility, called AccIni.Exe contains all the extra functionality needed to complete C3PA compliant installs. The binary (compiled) version of the utility is provided as a 32 bit, Local mode, Exe compiled in Clarion 5. It can be used with installs aimed at Clarion 4, Clarion 5 and Clarion 5.5 installations. Support for Clarion 2 has been removed from this binary release.

The source code for the utility is included in the Toolkit, however you MAY NOT distribute any modified version of the AccIni utility without the prior consent of the C3PA Toolkit Administrator (toolkit@c3pa.com). This is very important as all changes must be approved as compatible with prior, and future, versions.

The AccIni utility is designed to assist you with 4 tasks:

1.	Editing the Clarion.red file.
2.	Adding your documentation, and utilities, to the Accessories menu.
3.	Registering the template.
4.	Launching document files from the Accessories Menu.

It is designed to be called from inside an install script, and as such is not interactive. All commands, and parameters, are passed to the utility directly on the command line, or via an INI file. The utility does minimal checking of the parameters, and has no interactive windows of its own.

If Clarion is running while you attempt to do (1) or (2) above, then the utility will ask you to close Clarion before continuing. This is because Clarion caches the ABC library, template registry, and ini file - and installing any accessory with Clarion open can lead to complications. For item (3) Clarion has to be running, however AccIni will run Clarion as necessary.

It is intended that the AccIni utility be included with your install set, as it's presence on the destination machine cannot be guaranteed. The default directory for this file would be \Clarionx\3rdParty\Bin.

During an install script always do the Accessory Menu Items, and the RED file modifications before registering the template. This is because the first 2 items require that Clarion be closed. Registering the template requires that Clarion is running. AccIni is capable of (and will) start Clarion when necessary. However AccIni cannot automatically close Clarion - this must be done by the user.

Calling AccIni - General Information
You can pass the instructions to AccIni in one of 2 ways. Either directly on the command line, or via an INI File. The recommended method is using the command line for short commands, or the INI file for longer, or multiple, commands.

Calling AccIni via an INI file

Run Accini using the following syntax;

AccIni INI <IniFileName> <Remove>

The IniFileName is the name of the Ini file to use. If omitted then AccIni.Ini, in the Windows directory, is used.

If Remove is present then the ini file will be removed once the instructions have been completed.

Examples

AccIni INI
AccIni INI Fred.Ini
AccIni INI Fred.Ini Remove

The format of the ini file is as follows;

[AccIni]
NumCommands=n

[AccIni1]
Command1=command line parameter 1
Command2=command line parameter 2
Command3=command line parameter 3
Command4=command line parameter 4
Command5=command line parameter 5

[AccIni2]
Command1=command line parameter 1
Command2=command line parameter 2
Command3=command line parameter 3
Command4=command line parameter 4
Command5=command line parameter 5

and so on. Set NumCommands at the top to be equal to the number of commands to run in the file.

Example

[AccIni]
NumCommands=3

[AccIni1]
Command1=MENU
Command2=Help/File Manager 2
Command3=FM2Help
Command4=c:\clarion5\3rdparty\bin\AccIni RUN c:\clarion5\3rdparty\docs\fm2\fm2.htm
Command5=5

[AccIni2]
Command1=RED
Command2=Common
Command3=*.Ext
Command4=Path
Command5=5

[AccIni3]
Command1=TEMPLATE
Command2=FM2.TPL
Command3=5

How to use AccIni to view a document file
There are currently a number of formats used for help files. Different formats have different advantages and disadvantages. While the C3PA standards do not dictate the format that should be used, AccIni makes it easy to launch any format from inside the IDE. (We'll document adding items to the Accessories menu in a minute - but first lets look at the RUN command.)

By using the following syntax, you can launch the default viewer for any file type:

AccIni RUN "path\file.extension"

Where :

AccIni	Is the name of the utility
RUN	Is the Command, and tells AccIni you're wanting to run a program.
"path\file"	This is the name of the file you want to view. Note that the full path, the filename, and the extension must be included. For an example of this, see the next section, and the example for the docs there.

How to use AccIni to add to the Accessories menu
Add the following line, for each item to be added to the Accessories menu, to your install script, as an executable program:

AccIni MENU "Menu Item" "Tag" "Program Name" "ClarionVersion"

Where :

AccIni	Is the name of the utility
MENU	Is the Command, and tells AccIni we're dealing with a menu item
"Menu item"	This is the name which will appear on the Accessories menu. You can include sub-menus here by using a / character. For example, installing your docs would set this to "Help/MyProduct". To install your utility you would set this to "MyUtility".
"Tag"	This is a tag used internally by Clarion to link the menu item to the action. Use something that will be unique to your product.
"Program Name"	This is the complete name, of the program to run. If the program is not in the path on the users machine ( which it probably won't be) then include the full path to the program.
"Clarion Version"	The Target Clarion version. ie 4, 5 or 55

Examples:

AccIni MENU "Help/File Manager 2" "FM2Help" "c:\clarion5\3rdparty\bin\AccIni RUN c:\clarion5\3rdparty\docs\fm2\fm2.htm"

AccIni MENU "C-Scan" "CS" "c:\clarion5\3rdparty\bin\cs.exe"

Notice the use of the fill pathnames in the "Program Name" items.

How to use AccIni to change the Clarion.red file
For each item that you want to include in the Red file, add the following line to your install script, as a program to run:

AccIni RED Common "*.Ext" "Path" "ClarionVersion"

Where

AccIni	Is the name of the utility
Common	This is the Section inside the RED file to edit. This would be Common in almost all circumstances.
RED	Is the Command, and tells AccIni we're dealing with a Clarion.red file entry
*".Ext"**	This is the extension you want to add an entry for. for example, .DLL, or .LIB.
"Path"	This is the path where files of that type can be found.
"Clarion Version"	The Target Clarion version. ie 4, 5 or 55

Examples

AccIni RED Common "*.DLL" "c:\clarion5\3rdparty\bin" 5

AccIni RED Common "*.LIB" "c:\clarion5\3rdparty\lib" 5

How to use AccIni to Register a template
Add the following line, for each template to register, to your install script, as an executable program:

AccIni TEMPLATE "Template.tpl" "ClarionVersion"

Where :

AccIni	Is the name of the utility
TEMPLATE	Is the Command, and tells AccIni to register a template.
"Template.tpl"	This is the name of the template to register.
"Clarion Version"	The Target Clarion version. ie 4, 5 or 55

Examples:

AccIni TEMPLATE "fm2.Tpl" 4

How to use AccIni to set the PATH environment variable
Most install programs will allow you to edit the Path variable. However if your install program doesn't have that facility then you can do it using the AccIni program. To change the path add the following line to your install script, as an executable program:

AccIni ENV "Path" "AddToPath"

Where :

AccIni	Is the name of the utility
ENV	Is the Command, and tells AccIni to edit an environment variable
"Path"	This is the name of the environment variable to change.
"AddToPath"	The directory to add to the path.

Examples:

AccIni ENV "Path" "c:\clarion5\3rdparty\bin"

Using AccIni to bring a window to the front
To bring a window to the front of the screen, add the following line to your install script as an executable program:

AccIni BRINGTOFRONT "Window Title"

Where :

AccIni	Is the name of the utility
BRINGTOFRONT	Is the Command, and tells AccIni to bring the required window to the front.
"Window Title"	This is the exact title of the window to bring to the front.

Example:

AccIni BRINGTOFRONT "CapeSoft Office Messenger"

Using AccIni to close an application
To close an application, add the following line to your install script as an executable program:

AccIni CLOSE "Window Title" <Force>

Where :

AccIni	Is the name of the utility
CLOSE	Is the Command, and tells AccIni to close the required application.
"Window Title"	This is the exact title of the application window to close.
<Force>	Normally this value is set to 1. See the note below.

NOTE: The <FORCE> parameter is useful for closing applications such as Capesoft Office Messenger. If <FORCE> is set to 0, then only the currently open window is closed. With <FORCE> set to 1, the entire program is shut down and the icon is removed from the system tray.

Example:

AccIni CLOSE "CapeSoft Office Messenger" 1

Using AccIni to send a Windows message
This command invokes the Microsoft Windows command SendMessage. In order to send a message to the required window. add the following line to your install script as an executable program:

AccIni SENDMESSAGE "Window Title" <Message Number> <Parameter 1> <Parameter 2>

Where :

AccIni	Is the name of the utility
SENDMESSAGE	Is the Command, and tells AccIni to send a Windows message to the required window.
"Window Title"	This is the exact title of the required application window.
<Message Number>	This is the message value, defined in the Microsoft Windows header file WINUSER.H.
<Parameter 1>	The value of the first parameter.
<Parameter 2>	The value of the second parameter.

Example:

AccIni SENDMESSAGE "CapeSoft Office Messenger" 16 0 0

This example sends a WM_CLOSE message to the Office Messenger. This is equivalent to sending a CLOSE message with <FORCE> set to 0.

The AccIni Log file
AccIni keeps track of the functions that it's doing in a Log file. This can be very useful for debugging purposes. The name of the log file is AccIni.Log, and it's stored in the same directory as the AccIni exe program.

The log file is in a simple text format, which can be viewed in NotePad, or any other text editor.

AccIni supports the following commands which allow you to manipulate the log file via AccIni;

RESETLOG : This empties the log file.

eg : AccIni RESETLOG

COMMENT : This allows you to insert a comment into the log file.

eg : AccIni COMMENT "Start of File Manager 2 Installation"

Download the Toolkit
Download the toolkit here.