Using the ARS Perl extension

$Id: usage.html,v 1.6 1996/11/21 22:23:07 jcmurphy Exp jmurphy $

Note

This documentation is under construction.

Contents


Loading

To load the extension you must have 'use ARS;' at the beginning of a perl script. The added perl functions more or less match the ones in the C API. It should be noted that, at present, only functions pertinent to client usage are integrated. Functions that would be used, for instance, by the admin application are not integrated (i.e. functions for creating schemas,active links, etc. Only functions to fetch schemas, active links, submit and modify data are available).

SPECIAL VARIABLES

$ars_errstr
Error and warning messages from the C or Perl API are placed in this variable.

FUNCTION LIST

ars_Login(server,username,password)
Returns a control structure with the spacified server username and password. Specifying a null server will use whatever the default server is for your system.

On success
Returns a scalar control record.
On failure
Returns undef for invalid number of arguments.

Example:

      $c = ars_Login("","jmurphy","blah")
      
ars_Logoff(ctrl)
Releases the license for the control record given.

No return values.

Example:

      ars_Logoff($c);
      
ars_LoadQualifier(ctrl,schema,qualstring)
Converts a qualifier string into a scalar qualifier record.

On success
Returns the qualifier record.
On failure Returns undef.

Example:

      ($q = ars_LoadQualifier($c, "User", "'Login name' = \"jmurphy\"")) ||
	    die $ars_errstr;
      
ars_GetListField(control,schema,changedsince=0)
Fetches the Field ID's for all fields in the schema specified. changedsince is an optional unix timestamp and defaults to 0.

On success
Returns an array of field ids.
On failure
Returns undef.

Example:

      @fields = ars_GetListField($c, "User");
      
ars_GetFieldByName(control,schema,field_name)
This is a shortcut function that combine ars_GetListField and ars_GetField. Given a schema name and field name, it returns the field id. If you need more than a few field id's, use ars_GetFieldTable.

On success
Returns the field id.
On failure
Returns undef.

Example:

    
      $id = ars_GetFieldByName($c, "User", "Login name");
      
ars_GetFieldTable(control,schema)
This function is a combination of ars_GetListField and ars_GetField. It populates a hash (associative array) with field names and values. The keys of the hash are the field names, and the values of the hash are the field ids.

On success
Returns a hash of all fields in the schema.
On failure
Returns undef.

Example:

      (%fields = ars_GetFieldTable($c, "User")) || die $ars_errstr;
      $id = $fields{"Login name"};
      
ars_CreateEntry(ctrl, schema, field_name1, value1, ...)
This function creates a new entry (row) in the schema. This is the same as ``submitting a new ticket''. Pairs of field ids and values should follow the schema name. Data types are automatically converted.

On success
Returns the new entry id.
On failure
Returns undef.

Example:

      ($entry_id = ars_CreateEntry($c, "Schema01", $id, $val)) || 
            die $ars_errstr;
      
ars_DeleteEntry(ctrl,schema,entry_id)
This function deletes the entry (row) in the schema matching entry_id. Don't ask why it returns 0 on success.

On success
Returns 0.
On failure
Returns -1.

Example:

      if (ars_DeleteEntry(ctrl,"Schema01",$entry_id) == -1) {
	die $ars_errstr;
      }
      
ars_GetEntry(ctrl,schema,entry_id,...)
This function returns a hash (associative array) of field ids and values for a given schema and entry id. If you specify any field ids after the 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.

On success
Returns a hash. The keys of the hash are the field ids and the values are the field values.
On failure
Returns 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,...)
This function is used to retrieve the list of entry_ids 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.

On success
Returns a list of (entry_id, short-description) pairs.
On failure
Returns 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)
This function fetches the list of all schemas available to the user. changedsince is an optional timestamp that will cause only schemas newer than that time to be returned.

On success
Returns an array of schema's available.
On failure
Returns undef.

Example:

      @schemas = ars_GetListSchema($c);
      for($i = 0; $i < $#schemas ; $i++) {
           print "$schemas[$i]\n";
      }
      
ars_GetListServer(ctrl)
This function determines what servers are available from the machine that the script is running on.

On success
Returns an array of one or more servers as defined in the /etc/ar file.
On failure
Returns undef.

Example:

      @servers = ars_GetListServer($c);
      for($i = 0; $i < $#servers ; $i++) {
           print "$servers[$i]\n";
      }
      
ars_GetActiveLink(ctrl,name)
This function fetches information regarding a specified active link. See Data Structures below.

On success
A scalar pointer to the active link attributes.
On failure
undef.

Example:

      $alink = ars_GetActiveLink($c, "AR-Assets-GetContactinfo");
      
ars_GetCharMenuItems(ctrl,name)
This function builds a "linked list" of menu items. It returns an array pointer to the top level menu that is made up of (name, value) pairs. If the value is, in turn, another array pointer, then it points to a submenu structure.

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.

On success
A reference to an array.
On failure
undef.

Example:

      $m = ars_GetCharMenuItems($ctrl, $menu_name));
      @menu_struct = @$m;
      
ars_GetSchema(ctrl,name)
This function fetches the schema attributes. See Data Structures below.

On success
A scalar reference to the schema attributes.
On failure
undef

Example:

      $s = ars_GetSchema($c, "Group");
      
ars_GetListActiveLink(ctrl,schema=NULL,changedSince=0)
This function will look up the names of all active links, or a subset restricted to a certain schema name (if you provide a schema name).

On success
An array of Active Link names.
On failure
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)
Returns a hash reference to information about a field. The hash will contain the following elements:

fieldId
the field id of the field
createMode
will be one of: open, protected
option
dataType
will be one of: keyword, integer, real, char, diary, enum, time, or bitmask.
defaultVal
limit
this is a hash. it's keys are (depending upon the dataType):
min, max, precision
used the integer and real types (precision is only for reals).
maxLength
used for char type.
menuStyle
will be either append or overwrite
match
will be one of: anywhere, leading or equal
charMenu
contains the name of the menu attached to this field.
pattern
contains the pattern to match the field against.
fullTextOptions
will be one either none or indexed
displayList
helpText
timestamp
owner
lastChanged
changeDiary

On success
a hash
On failure
undef

Example:

      
ars_SetEntry(ctrl,schema,entry_id,getTime,...)
Modifies the value of an entry in a schema. alternating field ids and values should be given after getTime.
On success
Returns True (1)
On failure
Returns undefined

Example:

      
ars_GetListFilter(ctrl,schema=NULL,changedsince=0)
Returns an array of all available Filter names or a subset based upon the given schema name and timestamp.

On success
returns an array of strings
On failure
returns undef

ars_GetListCharMenu(ctrl,changedsince=0)
Returns an array of all available Menu names or a subset based upon the given timestamp.

On success
returns an array of strings
On failure
returns undef

ars_GetListEscalation(ctrl,schema=NULL,changedsince=0)
Returns an array of all available Escalation names or a subset based upon the given schema name and timestamp.

On success
returns an array of strings
On failure
returns undef

ars_GetListAdminExtension(ctrl, changedsince=0)
Returns an array of all available Admin Extension names or a subset based upon the timestamp.

On success
returns an array of strings
On failure
returns undef

ars_Export(ctrl, displayTag, type, name)
Returns a scalar consisting of the export text for the requested item name of the given type. Valid types are:

displayTag is the particular view to export. If you pass in an empty string for this parameter, all views will be exported.

On success
returns a scalar string
On failure
returns undef

ars_GetFilter(ctrl, name)
Returns a HASH consisting of filter attributes. name is the actual filter name as shown in the ARAdmin tool. See also: ars_GetListFilter and GetFilter Hash Values.

On success
returns a HASH
On failure
returns undef

ars_GetCharMenu(ctrl, name)
Returns a HASH consisting of menu attributes. 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.

On success
returns a HASH
On failure
returns undef

ars_GetServerStatistics(ctrl, statisticNumber)
Returns a HASH consisting of server statistics. 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";
	
On success
returns a HASH
On failure
returns undef

ars_GetProfileInfo(ctrl)
Returns a HASH consisting of ARSperl profiling statistics.

Here is an example:

	%profile = ars_GetServerStatistics($ctrl);
        
	print "startTime= ".$profile->{startTime}." queries=".$profile->{queries}."\n";
	
On success
returns a HASH
On failure
returns undef


Helper Functions

The following are some functions that are not part of the C extension code. These are simple functions that are part of the ARS Perl Module. They are intended to make life a little easier in some (specific) cases.
ars_simpleMenu(menu)
This is a perl routine in the ARS.pm perl module. It is primarily intended to make life a little easier for the Web client demo script. It converts a menu returned by ars_GetCharMenuItems to a single level menu seperating labels with '/'. This was added because of limitations in HTML.

On success
An array of menu items.
On failure
undef

Example:

      @sm = ars_simpleMenu(ars_GetCharMenuItems($ctrl, $menu_name));
      
ars_padEntryid(ctrl, schema, entry_id)
Pads entry_id with the required number of zeroes.

Data Structures

Contents

Status History Value

{"userOrTime"		=> integer,
 "enumVal"		=> integer}

Assign Field Structure

{"server"		=> string,
 "schema"		=> string,
 "qualifier"		=> reference to qualifier,
 "fieldId"		=> integer,
			or
 "statHistory"		=> reference to Status History Value}

Field Assign Structure

{"fieldId"		=> integer,
 "assignment"		=> reference to Assign Struct}

Display Structure

{"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}

Macro Parm Structure

(name : string, value : string)

Active Link Macro Structure

{"macroParms"		=> array of references to Macro Parm Structure,
 "macroText"		=> string,
 "macroName"		=> string}

Field Characteristics

{"accessOption"		=> integer,
 "focus"		=> integer,
 ["display"		=> reference to Display Structure,]
 ["charMenu"		=> string,]
 "fieldId"		=> integer}

Active Link Action Structure

{"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.

Entry List Field Structure

{"fieldId"		=> integer,
 "columnWidth"		=> integer,
 "separator"		=> string}

Index Structure

{["unique"		=> 1,]
 "fieldIds"		=> reference to a list of integers (internal ids)}

Field Limit Structure

; 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

Assign Structure

{"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 Assign Structure

(function : string, parameter...)

Arith Op Assign Structure

{"oper"			=> "+" or "-" or "*" or "/" or "%",
 "left"			=> reference to Assign Structure,
 ["right"		=> reference to Assign Structure]}

Value Structure

ARValueStruct is just converted to the associated perl type, except for keywords. Keywords are denoted by a string surrounded by nulls. For example, $TIMESTAMP$ is converted to the perl string "\0timestamp\0". C doesn't allow nulls in strings so this doesn't introduce any ambiguity.

GetFilter Hash Values

{
"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
}

GetFilter Action Hash Values

{
"notify"	=> reference to Notify Hash
"assign_fields"	=> reference to Field Assign Structure
"message"	=> string of form "Type # Num # Text [X..]",
"process"	=> string
}

GetFilter Action Hash/Notify Hash Values

{
"notifyText"		=> string,
"notifyPriority" 	=> integer,
"notifyMechanism"	=> integer enumeration,
"notifyMechanismXRef"	=> unknown,
"subjectText"		=> string,
"fieldIdListType"	=> integer enumeration,
"fieldList"		=> integer list (where applicable)
}

GetCharMenu Hash

{
"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)
}

GetCharMenu Query Hash

{
"schema"	=> string,
"server"	=> string,
"labelField"	=> integer,
"valueField"	=> integer,
"sortOnLabel"	=> integer boolean,
"qualifier"	=> internal pointer
}

GetCharMenu SQL Hash

{
"server"	=> string,
"sqlCommand"	=> string,
"labelIndex"	=> integer,
"valueIndex"	=> integer,
}

GetCharMenu File Hash

{
"fileLocation"	=> integer enumertion,
"filename"	=> string
}

GetProfile Hash

{
"startTime"	=> integer,
"queries"	=> integer
}

arsperl@smurfland.cit.buffalo.edu