A Guide to the use of AD2FILE.EXE with Arachne
AD2FILE's function is to add lines of text or HTML code to an existing file at a position in the file specified in an instruction set.
Before doing anything to the specified file, AD2FILE will place a copy of the unchanged file into the AD2FILE backup directory at arachne\ad2file\backup
. Just in case of accidents !!
It was conceived as an adjunct to the Arachne Package APM function, which does not otherwise have a facility to add links (for example) to an existing Arachne file.
Simply including a changed file, as part of an APM, could inadvertently destroy an already customised page file (e.g. utils.htm, mail.htm, saveas.ah - in my own case).
Using this utility to make the changes should not damage customised screen files. Hopefully !
AD2FILE is invoked by the line in your MIME.CFG:
file/ad2file.dgi |@cd ad2file \n ad2file.exe \n cd ..
When invoked, AD2FILE looks for its instruction file AD2FILE.DAT in the arachne\ad2file\ directory.
If the file is not found AD2FILE exits immediately and returns to Arachne - no harm done !
If the AD2FILE.DAT is found, then AD2FILE.EXE reads it to obtain the file to be changed, where the changes should go in that file, and what the new lines are.
If the target file is not found (e.g. if the path is written incorrectly or the file misspelled) then AD2FILE.EXE exits immediately - no harm done.
The target file is searched to make sure that the marker line is really there. If it is NOT found, then (you guessed it !) AD2FILE.EXE exits immediately - no harm done.
The target file is backed up to ad2file\backup.
The target file is re-written line by line, with the extra line(s) being put into the place specified in AD2FILE.DAT.
Messages are shown on your monitor as these things happen, and you are asked to press any key when it is all done.
The file AD2FILE.DAT is deleted - to avoid it being used again accidentally and writing the same extra lines twice into the same target file.
You are returned to Arachne.
What you get:
This package contains:
The executable file AD2FILE.EXE;
This Guide to AD2FILE
And the necessary new lines in MIME.CFG.
file/ad2file.dgi |@cd ad2file \n ad2file.exe \n cd ..
file/noadd.dgi |del ad2file\\ad2file.dat
file/ad2filesplash.dgi |@cd ad2file \n ad2file.exe /? \n cd ..
And another trick: calling AD2FILE /? will display an abbreviated HELP Screen.
The instruction file - AD2FILE.DAT:
This is the heart of this utility !
This file holds the instructions that AD2FILE.EXE will carry out, and it is important that it is prepared carefully.
It is in three parts:
First line: (the target)
Contains the path and filename of the target file - the one to be added to.
The path syntax must be in one of 2 forms, either:
"..\pathto\filename.ext" - remembering that a relative path starts in arachne\ad2file.
NOTE: For targeting a file in arachne_main, this will appear as file://filename.ext or ..\filename.ext.
This may be in upper or lower case, or a mixture of both, this line is NOT case-sensitive.
Second line: (the marker line)
Contains the whole of the line from the target file that will remain BELOW the inserted line(s).
This must be an EXACT match to a line in the target file - and IS case-sensitive, so be sure to get it exactly right.
NOTE: If the marker line appears more than once in the target file, then only the first instance of the marker line will be used.
If an exact match is not found, then AD2FILE.EXE will abort !
Third line and all other lines: (the text)
Are the line(s) in sequence that are to be written into the target file IMMEDIATELY ABOVE the "marker line", and may be in plain ASCII text, or HTML (or PHP) coding, or what ever is required.
If adding HTML coding, you may want to end this section with a <br> to avoid finding the "marker line" added to the last line of the added set.
1. To place a link into an existing Arachne file, for a new add-on to Arachne.
When creating the APM, include your ad2file.dat in the APM (to go into arachne\ad2file directory).
Place a link to the (file://ad2file.dgi) function in MIME.CFG, in the message screen displayed after the APM has been installed, with instructions to "click here to add [some required lines/links] to [filename]".
Also place a link to (file://noadd.dgi) for the option "Click here to prevent [some lines] being written to [some file], if you wish to make your own changes" in the same message display.
2. To add some extra text to an existing information screen file using an APM to do it.
Again, display the message to "click here" to add the extra lines, and "or click here" to NOT add the extra lines.
Also remember: If you are creating an APM that will rely on ad2file to make a link in, or add something to, an existing file, the recipient may not already have the ad2file.apm installed.
Therefore, it may be prudent to always include the contents of the ad2file.apm in YOUR APM as well as your APM-specific ad2file.dat.
i.e. the directory structure: arachne\ad2file\backup\!
and the files: arachne\ad2file\ad2file.exe
and : arachne\ad2file\ad2file.htm
and the required lines in MIME.CFG.
Ad2file by itself is not intended for casual Arachne users to experiment with.
It is a tool intended specifically for Arachne developers who are building APMs.
In addition... ad2file is not intended as, and will not work correctly as, a 'stand alone' application, because it is NOT a stand alone application.
IT CAN DAMAGE YOUR ARACHNE INSTALLATION IF NOT USED CORRECTLY !
It will only work correctly when used in conjunction with an Arachne APM.
IMPORTANT: ad2file.exe is ONLY for creating extra function in an APM.
Package authors should contact either of the two culprits below for advice and information on how to go about activating ad2file.exe, because it is almost totally passive (i.e. non-active) without a trigger.