pconfig()

Manage the PATROL Agent configuration variables.

Syntax

pconfig(APPEND,variable,[value])
pconfig(DELETE,variable,[value])
pconfig(FORMAT,[options],[name_separator],[value_separator],
[variable])
pconfig(GET,variable)
pconfig(LIST)
pconfig(PURGE)
pconfig(RELOAD)
pconfig(REPLACE,variable,[value])

Parameter

Parameter	Definition
variable	string identifying the PATROL Agent configuration variable on which pconfig() is to act The variable parameter is validated using the following rules: ■ composed of name segments separated by a slash (/) ■ may start with a slash (/), but not end with a slash(/) ■ may not contain empty segments ■ may not contain unprintable characters ■ may not contain white space other than the space character ■ may contain spaces within a segment but not at the beginning or end of a segment
value	optional string identifying the value associated with variable Default NULL string You can assign multiple values using a comma to separate values in the string as follows: "value1,value2, . . . , valuen".
options	optional bitmask of preferences that specifies the variables to be returned and how they are to be formatted
name_separator	optional string to output after the name of variable
value_separator	optional string to output after the value of variable

Description

The pconfig() function can be used to view and change the configuration variables for a PATROL Agent. Changes made with the pconfig() function take effect immediately without restarting the PATROL Agent, and these changes are persistent and will survive a PATROL Agent restart.

The following topics describe each of the pconfig() options. (See the PATROL Agent Reference Manual for more information about PATROL Agent configuration.)

APPEND Option

The pconfig("APPEND") function appends value to the list of values for variable. If variable does not exist, thepconfig("APPEND") function creates variable and adds value to it.

The pconfig("APPEND") function does not check to see if variable already has value in its list of values. (If so, thepconfig("APPEND") function adds it a second time.)

The pconfig("APPEND") function returns the NULL string and sets the PSL variable errno = 0 (E_PSL_NO_ERROR) if successful, or a PSL error message string and nonzero errno return value otherwise. (See pconfig() Function Messages and Return Codes)

DELETE Option

The pconfig("DELETE") option deletes the variable information from the PATROL Agent configuration:

If both variable and value are specified, the pconfig("DELETE") function deletes value from variable
If only variable is specified, the pconfig("DELETE") function deletes variable from the PATROL Agent configuration.

If variable does not exist in the PATROL Agent configuration, the pconfig("DELETE") function performs no operation.

The pconfig("DELETE") function returns the NULL string and sets the PSL variable errno = 0 (E_PSL_NO_ERROR) if successful, or a PSL error message string and nonzero errno return value otherwise. (See pconfig() Function Messages and Return Codes)

Examples of the pconfig("DELETE") Option

To delete the value of the variable:
"/AgentSetup/defaultAccount" = { DELETE = "" }
To delete the variable:
"/AgentSetup/defaultAccount" = { DELETE }

FORMAT Option

The pconfig("FORMAT") returns a list of PATROL Agent configuration variables or a single configuration variable in the format that you specify. The pconfig("FORMAT") call is similar to pconfig("GET") and pconfig("LIST" ) calls, but it can be a little more flexible in some situations.

The options parameter is a bitmask of preferences that specifies the variables to be returned and how they are to be formatted. The available option preferences areas follows:

Value	Option preference
64	Place quotes around name and values
32	Search for given variable only
16	Output default variables
8	Output overridden/non-default variables
4	Output variable names
2	Output current values
1	Output default values

Combinations of these preferences can be specified by ORing the values together. For example, if options is set to 18 (that is, 16 | 2), then the pconfig("FORMAT") option returns the current values of the default variables.

The name_separator and value_separator parameters specify the strings that should appear after each variable name and each value respectively.

The last parameter variable specifies the name of the variable that should be returned. Without variable,pconfig("FORMAT") is a generalized form of pconfig("LIST") but with a specified variable.

The following table lists the parameters that are optional along with their default values:

Parameter	Default Value
options	4
name_separator	\n
value_separator	\n
variable	""

If the pconfig("FORMAT") function cannot obtain the list of variables or the value of a variable, it returns a PSL error message string and a non-zero errno return value. (See pconfig() Function Messages and Return Codes)

Examples of the pconfig("FORMAT") Option

# Get just the current value
pconfig("FORMAT",32|2,"","",
"/AgentSetup/historyRetentionPeriod");
# List out only non-default/overridden variables
# with name=value<newline> format
print(pconfig("FORMAT",8|4|2,"=","\n",""));

GET Option

The pconfig("GET") function returns the default and current values of variable in a PSL list with the following format:

default_value\n
current_value

If the specified variable does not exist, the pconfig("GET") function returns a NULL string and sets the errno variable to a non-zero value.

LIST Option

The pconfig("LIST") function returns a list of all the PATROL Agent configuration variables in a PSL list with the following format:

variable1\n
variable2\n
. . .
variablen

If the pconfig("LIST") function cannot obtain the list of variables, it returns a PSL error message string and a nonzeroerrno return value.

PURGE Option

The pconfig("PURGE") function removes the existing configuration from the PATROL Agent and creates a new one based on the PATROL Agent config.default file.

The pconfig("PURGE") function returns the NULL string and sets the PSL variable errno = 0 (E_PSL_NO_ERROR) if successful or a PSL error message string and nonzero errno return value otherwise. (See pconfig() Function Messages and Return Codes)

RELOAD Option

The pconfig("RELOAD") function reloads the default configuration information from the PATROL Agent config.defaultfile only if the timestamp on config.default has been updated since the last time it was read by the PATROL Agent. (The PATROL Agent keeps the timestamp of the last config.default file it read in the configuration database files.) Thepconfig("RELOAD") function will not modify any user-created variables or values, but will replace any default variables and values that are different than those in config.default.

The pconfig("RELOAD") function returns the NULL string and sets the PSL variable errno = 0 (E_PSL_NO_ERROR) if successful or a PSL error message string and nonzero errno return value otherwise. (See pconfig() Function Messages and Return Codes)

REPLACE Option

The pconfig("REPLACE") function replaces all existing values of variable with value:

If variable does not exist, the pconfig("REPLACE") function creates variable and adds value to it.
If variable exists and has no values, the pconfig("REPLACE") function adds value to variable.
If value is already in the list of values for variable, the pconfig("REPLACE") function deletes all other values so that only value remains.

The pconfig("REPLACE") function returns a string containing the new value of the agent configuration variable and sets the PSL variable errno = 0 (E_PSL_NO_ERROR) when successful or a PSL error message string and nonzero errnoreturn value otherwise. (See pconfig() Function Messages and Return Codes)

pconfig() Function Messages and Return Codes

The pconfig() function detects and reports any of several error conditions by returning text string messages and setting the PSL variable errno. The following table summarizes the relationship between the errno return codes and thepconfig() function messages. The topics following the table briefly describe the pconfig() function messages.

PSL errno variable		pconfig() return value
Value	Message	Message
0	E_PSL_NO_ERROR	NULL string (except for LIST and GET options)
96	E_PSL_BAD_FUNCTION_PARAMETER	Syntax Error: pconfig argument 1 missing Syntax Error: argument 1 is invalid Syntax error: pconfig argument 2 is missing Syntax error: pconfig argument 2 is not a valid variable name Syntax error: pconfig argument 5 is not a valid variable name
117	E_PSL_ACL_FAILED	Configuration: write access not allowed due to ACL
118	E_PSL_CONFIG_FAILED	Configuration: Database PURGE failed Configuration: Database RELOAD failed

Configuration: write access not allowed due to ACL

The pconfig() function returns this text string to indicate that it was unable to write to the PATROL Agent configuration file because of Access Control List (ACL) restrictions. That is, the account under which the pconfig() command executed does not have permission to write to the PATROL Agent configuration file. When the pconfig() function returns this message, it sets the PSL variable errno = 117 (E_PSL_ACL_FAILED). The pconfig() function can return this message for the APPEND, DELETE, MERGE, PURGE, RELOAD, and REPLACE options.

Configuration: Database PURGE failed

The pconfig() function returns this text string to indicate that it was unable to purge the PATROL Agent configuration file. (Either it could not remove the existing file, or it could not create the new file from the config.default file). When thepconfig() function returns this message, it sets the PSL variable errno = 118 (E_PSL_PCONFIG_FAILED). Thepconfig() function can return this message for the PURGE option.

Configuration: Database RELOAD failed

The pconfig() function returns this text string to indicate that it was unable to reload the PATROL Agent configuration file default values from the config.default file. (This can be a config. default file problem or a problem reading the configuration database files.) When the pconfig() function returns this message, it sets the PSL variable errno = 118 (E_PSL_PCONFIG_FAILED). The pconfig() function can return this message for the RELOAD option.

NULL String

The pconfig() function returns the NULL string to indicate it successfully completed the operation. When the pconfig()function returns this message, it sets the PSL variable errno = 0 (E_PSL_NO_ERROR). The pconfig() function returns this message for the APPEND, DELETE, MERGE, PURGE, RELOAD, and REPLACE options.

Syntax Error: pconfig argument 1 missing

The pconfig() function returns this text string to indicate that no option ( APPEND, DELETE, FORMAT, MERGE, and so on) was specified. When the pconfig() function returns this message, it sets the PSL variable errno = 118 (E_PSL_PCONFIG_FAILED).

Syntax Error: argument 1 is invalid

The pconfig() function returns this text string to indicate that the specified option was not one of APPEND, DELETE, FORMAT,GET, LIST, MERGE, PURGE, RELOAD, or REPLACE. When the pconfig() function returns this message, it sets the PSL variable errno = 96 (E_PSL_BAD_FUNCTION_PARAMETER).

Syntax Error: pconfig argument 2 missing

The pconfig() function returns this text string to indicate that its option requires variable and variable was not specified. (The value is always optional and always defaults to the NULL string when omitted.) When the pconfig() function returns this message, it sets the PSL variable errno = 96 (E_PSL_BAD_FUNCTION_PARAMETER). The pconfig() function can return this message for the APPEND, DELETE, GET, MERGE, and REPLACE options.

Syntax Error: pconfig argument 2 is not a valid variable name

The pconfig() function returns this text string to indicate that the variable parameter has an invalid syntax. When thepconfig() function returns this message, it sets the PSL variable errno = 96 (E_PSL_BAD_FUNCTION_PARAMETER). The pconfig() function can return this message for the APPEND, DELETE, GET, MERGE, and REPLACE options.

Syntax Error: pconfig argument 5 is not a valid variable name

Example

The following examples show a couple of ways to use the pconfig() function.

pconfig() Function Options

The following PSL script contains examples of the pconfig() function and its different options:

# Get the value for a configuration variable
function InetVarGet( app, inst, var ) {
local varpath;
varpath = "/InetSetup/" . app . "/" . inst . "." . var;
# Looking up the (non-default) configuration vars
return( nthlinef(pconfig("GET", varpath), 2, "") );
}
# Set the value of a configuration variable
function InetVarSet( app, inst, var, val ) {
local varpath;
varpath = "/InetSetup/" . app . "/" . inst . "." . var;
return( pconfig("REPLACE", varpath, val) );
}
# Delete a configuration variable
function InetVarDelete( var ) {
return( pconfig("DELETE", var) );
}
# Get a list of configuration variables
function InetVarList( expr ) {
local tlist, all_list;
all_list = pconfig("LIST");
tlist = grep("^/InetSetup/", all_list);
if (expr) {
tlist = grep( expr, tlist);
}
return( sort( tlist ) );
}

Sample from the Make Current KM's Preloaded Menu Command

The following script uses the pconfig() function as part of the PSL script for a Make Current KM's Preloaded menu command:

requires response_def_lib;
requires unix_misc_lib;
response_def();
from = get_console_info();
if(console_type() != 1) {
error_pop-up("Only a Developer Console can set preloaded KM's");
event_trigger("0", "41", "INFORMATION", 9, "Attempt to set preloadedKMs by ".from);
exit;
}
buf = system("%DUMP KM_LIST");
buf = nthlinef(buf,"4-".(int(lines(buf)) - 1));
kms = "";
foreach lin (buf){
kms = kms . ntharg(lin, 2) . ".km=1\n";
}
kms = sort(kms);
resp_ret = response("Make Current KM's Preloaded",-1,"h=430,w=395",
LABEL."Select KM's to preload (default: all)",
SEP_HORIZ,
LIST_MULTIPLE.kms,
RADIO_HORIZ."Merge into preload list=1\nOnly preload these=0\n"
);
act = trim(nthlinef(resp_ret,1), "\n");
if(act){
sel_list = trim(nthlinef(resp_ret,2), "\n");
merge_rep = trim(nthlinef(resp_ret,3), "\n");
work = "";
foreach word sel_num (sel_list) {
work = work . nthargf(nthlinef(kms, sel_num), 1, "=") . "\n";
}
maxlen = get("/maxConfigValLen");
if(length(kms) > maxlen){
error_pop-up("KM list too long, cannot quick-set");
exit;
}
if(merge_rep == 1){
method = "MERGE";
yn = rusure("Merge these into preloaded KM list?\n\n".work);
}
else {
method = "REPLACE";
yn = rusure("Set preloaded KM list to:\n\n".work);
}
if(yn == 1){
kms = ntharg(work, "1-", "\n", ",");
event_trigger("0", "41", "INFORMATION", 9,
"/AgentSetup/preloadedKMs changed by ".from);
pconfig(method, "/AgentSetup/preloadedKMs", kms);
}
}