|
|
Guidelines for Writing APG Scripts |
|
See Also: |
In APGen, output streams are created by calling Output.Open() (or by letting APGen implicitly call Output.Open()) or by setting the Output.Stream property. Output.Open() is used more often than Output.Stream.
Opening an output stream is easy to do, and is discussed in the API documentation. This topic discusses when to open the output stream.
As a rule:
The output file should be set, or the output stream should be set, before any content is generated.
Most often, developers should set the output file by setting Output.Filename or Output.Path values before generating any content. After setting the output file, Output.Open() can be called, which opens/creates the output file. Output.Open() does not
have to be explicitly called: It is implicitly called as soon as content is
generated.
Both of these short examples obey this rule. The first example sets the output file before generating content:
<%#
Output.Filename = "default.htm"
Output.Unicode = False
#%><html><head>...
The second example sets the output stream of a second APG script (test.apg) before running it:
<%#
Dim oStream
' ...
' Assume oStream points to a valid stream object
' Run APG script test.apg
Dim oScript
Set oScript = APGen.OpenScript("test.apg")
' Redirect test.apg's output to oStream
oScript.Output.Stream = oStream
' Run test.apg
' test.apg generates content, which is written to oStream.
' test.apg should not set an output file or stream.
oScript.Run
#%>
As mentioned previously, Output.Open() is implicitly called as soon as content is generated.
Output.Open()uses values from Filename,
Dir, Path, Append, and CanCreateDirs to open the output file. All of these properties can be set before calling Output.Open(). Properties Append and CanCreateDirs have default values that work well in most situations. Properties Filename, Dir, and Path define the output file path. These properties also have default values, but in most cases, at least the Filename property should be explicitly set.
If the output file path is not set, a default path is used: The default output file is named <APG script name>.htm. The default output directory is the same directory that contains the APG script.
Content is generated when content blocks are executed, when output expressions are evaluated, or when Output.Write() or Output.BinaryWrite() are called.
When the first non-empty content block is written, a new output file is created using the Output.Path
value. All generated content is sent to this file.