$ars_errstr
ars_Login(server,username,password)
undef
for invalid number of arguments.
Example:
$c = ars_Login("","jmurphy","blah")
ars_Logoff(ctrl)
No return values.
Example:
ars_Logoff($c);
ars_LoadQualifier(ctrl,schema,qualstring)
undef
.
Example:
($q = ars_LoadQualifier($c, "User", "'Login name' = \"jmurphy\"")) || die $ars_errstr;
ars_GetListField(control,schema,changedsince=0)
changedsince
is an optional unix timestamp
and defaults to 0.
undef
.
Example:
@fields = ars_GetListField($c, "User");
ars_GetFieldByName(control,schema,field_name)
undef
.
Example:
$id = ars_GetFieldByName($c, "User", "Login name");
ars_GetFieldTable(control,schema)
undef
.
Example:
(%fields = ars_GetFieldTable($c, "User")) || die $ars_errstr; $id = $fields{"Login name"};
ars_CreateEntry(ctrl, schema, field_name1, value1, ...)
undef
.
Example:
($entry_id = ars_CreateEntry($c, "Schema01", $id, $val)) || die $ars_errstr;
ars_DeleteEntry(ctrl,schema,entry_id)
entry_id
. Don't ask why it returns 0 on success.
Example:
if (ars_DeleteEntry(ctrl,"Schema01",$entry_id) == -1) { die $ars_errstr; }
ars_GetEntry(ctrl,schema,entry_id,...)
entry_id
parameter, only the values
for those fields will be returned, otherwise all field id value pairs
are returned. All field values are converted into numeric or string
values, except for the diary type. The diary field type is encoded
as an array of hashes. Each hash has a timestamp, user and value
field.
undef
.
Example:
(%f = ars_GetFieldTable($c, "User")) || die $ars_errstr; (%vals = ars_GetEntry($c, "User", $entry_id)) || die $ars_errstr; print "Login name = ".$vals{$f{"Login name"}}."\n";
Example of decoding a diary field:
$diaryfield_fid = ars_GetFieldByName($ctrl, $schema, $diaryfield); %vals = ars_GetEntry($ctrl, $schema, $entry_id, $diaryfield_fid); foreach $diary_entry (@{$vals{$diaryfield_fid}}) { print "$diary_entry->{timestamp}\n"; print "$diary_entry->{user}\n"; print "$diary_entry->{value}\n"; }
ars_GetListEntry(ctrl,schema,qualifier,maxRetrieve,...)
entry_id
s
and description strings from the specified schema. The entries
are returned as an array of (entry_id, short-description) pairs.
If you wish to retrieve all entries in the schema (upto the maximum
allowed, or maxRetrieve) you should load a Qualifier with something
like (1 = 1)
. The "short-description" mentioned above is not the contents of the "short-description" field in the schema. It is a concatenation of a list of fields specified by the "Query List Fields" for this schema. See List_Entries.pl for an example.
An optional list of field ids and sorting type may be given after maxRetrieve to specify the sorting order. The sorting type can be 1 for ascending, or 2 for descending. Also, note that if you want to retain the order of the entry ids returned, then you must assign the list to an array, and not a hash.
Setting maxRetrieve = 0
will return as many matches as
the server will allow.
undef
.
Example:
%entries = ars_GetListEntry($c, "User", $q, 100); foreach $entry_id (sort keys %entries) { print "EntryID: $entry_id Short-Descrip: $entries{$entry_id}\n"; }
Example of how to set sorting options:
# returns entries for User schema sorted by login name $all = ars_LoadQualifier($c,"User","1=1"); $login_name = ars_GetFieldByName($c,"User","Login Name"); @a = ars_GetListEntry($c, "User", $all, 0, $login_name, 1);
ars_GetListSchema(ctrl, changedsince=0)
changedsince
is an optional timestamp that will cause
only schemas newer than that time to be returned.
undef
.
Example:
@schemas = ars_GetListSchema($c); for($i = 0; $i < $#schemas ; $i++) { print "$schemas[$i]\n"; }
ars_GetListServer(ctrl)
/etc/ar
file.
undef
.
Example:
@servers = ars_GetListServer($c); for($i = 0; $i < $#servers ; $i++) { print "$servers[$i]\n"; }
ars_GetActiveLink(ctrl,name)
undef
.
Example:
$alink = ars_GetActiveLink($c, "AR-Assets-GetContactinfo");
ars_GetCharMenuItems(ctrl,name)
Illustration
@menu_struct ($name = "Item1" , $value = "This is item1") . . . ($name = "Sub Menu", $value = array reference) +------> @sub_menu_struct ($name = "SubItem1", $value = ...) . . .See Show_Menu.pl for a demonstration of using this function and its output.
undef
.
Example:
$m = ars_GetCharMenuItems($ctrl, $menu_name)); @menu_struct = @$m;
ars_GetSchema(ctrl,name)
undef
Example:
$s = ars_GetSchema($c, "Group");
ars_GetListActiveLink(ctrl,schema=NULL,changedSince=0)
undef
Example:
@alink_names = ars_GetListActiveLink($c); # get all active links @alink_names = ars_GetListActiveLink($c, "Group"); # get all active links associated with the # "Group" schema.
ars_GetField(ctrl,schema,id)
Example:
ars_SetEntry(ctrl,schema,entry_id,getTime,...)
Example:
ars_GetListFilter(ctrl,schema=NULL,changedsince=0)
ars_GetListCharMenu(ctrl,changedsince=0)
ars_GetListEscalation(ctrl,schema=NULL,changedsince=0)
ars_GetListAdminExtension(ctrl, changedsince=0)
ars_Export(ctrl, displayTag, type, name)
displayTag is the particular view to export. If you pass in an empty string for this parameter, all views will be exported.
ars_GetFilter(ctrl, name)
name
is the actual filter name as shown in the ARAdmin tool. See also:
ars_GetListFilter and
GetFilter Hash Values.
ars_GetCharMenu(ctrl, name)
name
is the actual menu name as shown in the ARAdmin tool. See also:
GetCharMenu Hash Values.
Note: This function returns information about the menu. It does not return the actual menu items. See ars_GetCharMenuItems for that.
ars_GetServerStatistics(ctrl, statisticNumber)
statisticNumber
is the enumerated statistic value as listed in the ar.h
header file. In addition, you can use the ARServerStats
hash to convert from a statistic name to a statistic number.
Here is an example:
%stats = ars_GetServerStatistics($ctrl, $ARServerStats{'START_TIME'}, $ARServerStats{'API_REQUESTS'});This will return a HASH where the key is the enumerated value of the requested statistic and the value of the hash is the actual statistic value. To reference a statistic in the above HASH you can do this:
print $stats{$ARServerStats{'START_TIME'}}."\n";
ars_GetProfileInfo(ctrl)
Here is an example:
%profile = ars_GetServerStatistics($ctrl);
print "startTime= ".$profile->{startTime}." queries=".$profile->{queries}."\n";
ars_simpleMenu(menu)
undef
Example:
@sm = ars_simpleMenu(ars_GetCharMenuItems($ctrl, $menu_name));
ars_padEntryid(ctrl, schema, entry_id)
{"userOrTime" => integer, "enumVal" => integer}
{"server" => string, "schema" => string, "qualifier" => reference to qualifier, "fieldId" => integer, or "statHistory" => reference to Status History Value}
{"fieldId" => integer, "assignment" => reference to Assign Struct}
{"displayTag" => string, "label" => string, "labelLocation" => "Left" or "Top" "type" => "NONE" or "TEXT" or "NUMTEXT" or "CHECKBOX" or "CHOICE" or "BUTTON" "length" => integer, "numRows" => integer, "option" => "VISIBLE" or "HIDDEN" "x" => integer, "y" => integer}
(name : string, value : string)
{"macroParms" => array of references to Macro Parm Structure, "macroText" => string, "macroName" => string}
{"accessOption" => integer, "focus" => integer, ["display" => reference to Display Structure,] ["charMenu" => string,] "fieldId" => integer}
{"macro" => reference to Active Link Macro Structure, or "assign_fields" => reference to Field Assign Structure, or "process" => string, or "message" => string, or "characteristics" => Field Characteristics, or "dde" => not implemented, or "none" => undef}
"Message"
is formatted as:
This is the text
You can parse this with a regular expression.
{"fieldId" => integer, "columnWidth" => integer, "separator" => string}
{["unique" => 1,] "fieldIds" => reference to a list of integers (internal ids)}
; integer {"min" => integer, "max" => integer} or ; real {"min" => float, "max" => float, "precision" => integer} or ; char {"maxLength" => integer, "menuStyle" => "append" or "overwrite", "match" => "anywhere" or "leading" or "equal", "charMenu" => string, "pattern" => string, "fullTextOptions" => "none" or "indexed"} or ; diary {"fullTextOptions" => "none" or "indexed"} or ; enum and bitmask array of strings or undef
{"none" => undef, or "value" => reference to Value Structure, or "field" => reference to Assign Field Structure, or "process" => string, or "arith" => reference to Arith Op Assign Structure, or "function" => reference to Function Assign Structure, or "dde" => not implemented}
(function : string, parameter...)
{"oper" => "+" or "-" or "*" or "/" or "%", "left" => reference to Assign Structure, ["right" => reference to Assign Structure]}
{ "name" => string, "order" => integer, "schema" => string, "opSet" => integer bitmask, "enable" => integer boolean, "query" => reference to internal struct, "actionList" => list of references to Action Hash "helpText" => string, "timestamp" => integer, "owner" => string, "lastChanged" => integer, "changeDiary" => encoded string }
{
"notify" => reference to Notify Hash
"assign_fields" => reference to Field Assign Structure
"message" => string of form "Type # Num # Text [X..]
",
"process" => string
}
{ "notifyText" => string, "notifyPriority" => integer, "notifyMechanism" => integer enumeration, "notifyMechanismXRef" => unknown, "subjectText" => string, "fieldIdListType" => integer enumeration, "fieldList" => integer list (where applicable) }
{ "name" => string, "helpText" => string, "timestamp" => integer, "owner" => string, "lastChanged" => string, "changeDiary" => encoded string, "schema" => string "menuType" => integer enumeration, "menuQuery" => reference to CharMenu Query Hash (if menuType is Query) "menuSQL" => reference to CharMenu SQL Hash (if menuType is SQL) "menuFile" => reference to CharMenu File Hash (if menuType is File) }
{ "schema" => string, "server" => string, "labelField" => integer, "valueField" => integer, "sortOnLabel" => integer boolean, "qualifier" => internal pointer }
{ "server" => string, "sqlCommand" => string, "labelIndex" => integer, "valueIndex" => integer, }
{ "fileLocation" => integer enumertion, "filename" => string }
{ "startTime" => integer, "queries" => integer }