Ns adp ctl

<manpage>ns_adp_ctl</manpage>

NAME

ns_adp_ctl - Control current ADP execution environment (new in AOLserver 4.5)

SYNOPSIS

ns_adp_ctl option ?bool | arg?

DESCRIPTION

This command enables control of the current ADP execution environment. See Notes for an important known issue

Aside from the bufsize and chan subcommands, they all return a boolean value for a given ADP option. If the bool argument is given, the option is set to the given value and the previous value is returned.

Most of the options have equivalent config file settings which provide the server defaults in the ns/server/servername/adp section.

The legal options (which may be abbreviated) are:

• ns_adp_ctl bufsize ?size?

This command returns the current ADP output buffer size, setting it to a new value if the optionial size argument is specified. bufsize config setting defaults to 1000 KB.

• ns_adp_ctl chan channel

This command is used to specify an open file channel to receive output when the buffer is flushed. If channel is the null string, the output channel is cleared. This capability can be useful for specialized uses of ADP outside the context of an HTTP connection, e.g., for debugging or testing.

• ns_adp_ctl autoabort ?bool?

Query or set the autoabort option. When enabled, failure to flush a buffer (normally the result of a closed HTTP connection) generates an ADP exception, unwinding the ADP call stack. autoabort config setting defaults to true.

• ns_adp_ctl detailerror ?bool?

Query or set the detailerror option. When enabled, errors in ADP pages are formatted with information about the context of the HTTP request. This can be very helpful in debugging ADP errors but potentially a security risk if the HTTP context (e.g., cookie headers) contains personal or sensitive data. Errors are logged to the server log and, if displayerror is enabled, appened to the output buffer. detailerror config setting defaults to true.

• ns_adp_ctl displayerror ?bool?

Query or set the displayerror option. When enabled, errors in ADP pages are formatted and appended to the output stream, normally visiable to a user's browser. This option should generally be enabled in development and disabled in production. displayerror config setting defaults to false.

• ns_adp_ctl expire ?bool?

Query or set the expire option. When enabled, the ADP request processing code adds an "Expires: now" header in the response buffer to disable any caching. In practice, more thoughtful cache control mechanisms should be used based on the HTTP/1.1 spec. enableexpire config setting defaults to false.

• ns_adp_ctl gzip ?bool?

Query or set the gzip option. When enabled, the output buffer is compressed before being returned in the response. As ADP's are generally used to generate text data such as HTML or XML, compression is normally quite successful at reducing the response size. gzip config setting defaults to false.

In AOLserver 4.0, ns_adp_compress command (now deprecated) did the same thing but did not return anything. Note that in AOLserver 4.5, this flag is separate from the ns_conn compress flag and while you can use this to enable compression for the current ADP request, you cannot use this to disable the ns_conn compress flag, which if set to enabled (by a filter for example) will override your attempt to disable using this command.

• ns_adp_ctl ignorefinalflusherrors ?bool?

New in 4.5.2: Query or set the IgnoreFinalFlushErrors option. Flushing ADP output buffer at the end of processing an adp page might occur after the connection is already closed (i.e. browser has disconnected). In addition, pre-AOLserver 4.5 code could omit a call to ns_adp_abort when doing an ns_returnredirect or the like without ill effects, whereas in AOLserver 4.5 this causes an error to be logged. It is therefore desirable to have the option to ignore these errors altogether which was the behavior prior to version 4.5. When this setting is on, flush errors that occur at the end of the request are silently ignored without causing an error to be logged. Flush errors that occur in the middle of a request such as when streaming or using ns_adp_flush or when the ADP buffer overflows will continue to throw errors. IgnoreFinalFlushErrors config setting defaults to false.

• ns_adp_ctl nocache ?bool?

Query or set the nocache option. When enabled, all requests to cache executed ADP blocks via the ns_adp_include -cache directive are ignored, resulting in normal execution of all code.

• ns_adp_ctl safe ?bool?

Query or set the safe option. When enabled, all code is executed in "safe" mode, disabling and ignoring any code within <% ... %> tags and only allowing execution of previously defined registered tags. safeeval config setting defaults to false.

• ns_adp_ctl singlescript ?bool?

Query or set the singlescript option. When enabled, ADP pages are converted from independent text-script blocks into a single script, with text blocks replaced with a call to ns_adp_append with the given text. singlescript config setting defaults to false.

The purpose of this option is to enable tcl code that spans blocks, similar to old-style Microsoft ASP. While this can sometimes be convenient, it is not a recommended practice. Also, one side-effect of this is that an error anywhere on the page will result in the entire ADP page returning instead of skipping to the next block which is the normal behavior, just like with stricterror on. Example adp script that only works with singlescript on:

    <%
      while {[ns_db getrow $db $row]} {
    %>
        Blah <%=[ns_set get $row blah]%>
        ...more html code goes here...
    <%
      }
    %>

• ns_adp_ctl stricterror ?bool?

Query or set the stricterror option. When enabled, the result is similar to that of singlescript in that an error in a particular block will abort execution and return the current buffer instead of continuing to the next text or script block. stricterror config setting defaults to false.

• ns_adp_ctl trace ?bool?

Query or set the trace option. When enabled, the first X characters of each compiled adp block are logged to the server log. X defaults to 40 characters and can be configured only in the config file using the tracesize setting.

• ns_adp_ctl trimspace ?bool?

Query or set the trimspace option. When enabled, any white space at the start of the output buffer is eliminated. White space can show up in the output as a result of ADP pages which do nothing but include other ADP's in a way to reuse code with the unfortunate side effect of the training newline at the end of a "<% ns_adp_include myfile.adp %>" ending up in the output stream. trimspace config setting defaults to false.

NOTES

IMPORTANT: While this command is typically used in requests for adp pages, you can also use it in requests for registered procedures, scheduled procs, etc. that ns_adp_parse adp scripts or pages. One common setting you might set in such context is displayerror or safe. Currently, when ns_adp_ctl is used to set settings outside of an adp request, the configuration changes are NOT cleared at the end of the request and are persisted between connections for the given thread!

SEE ALSO

ns_adp_abort, ns_adp_append, ns_adp_argc, ns_adp_argv, ns_adp_bind_args, ns_adp_break, ns_adp_close, ns_adp_debug, ns_adp_debuginit, ns_adp_dir, ns_adp_dump, ns_adp_eval, ns_adp_exception, ns_adp_include, ns_adp_mime, ns_adp_mimetype, ns_adp_parse, ns_adp_puts, ns_adp_registeradp, ns_adp_registerproc, ns_adp_registertag, ns_adp_return, ns_adp_safeeval, ns_adp_stats, ns_adp_stream, ns_adp_tell

---