ARSperl: Usage

Using the ARS Perl extension

Note

This documentation is under construction.

Loading the extension
Reserved variables
- ars_errstr
Functions overview
Perl helper functions
- ars_simpleMenu
- ars_padEntryid
Data structures

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)

Attempts to login to the server.

On success: Returns a scalar control record.
On failure: Returns undef.

Example:

      ($c = ars_Login("server","jmurphy","blah")) || die "can't login";

ars_Logoff(ctrl)

Closes an active session 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\"")) ||
	    print "error!";

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)

An easier way of looking up field attributes. This function allows you to retrieve the Field ID (used by many functions) by just knowing the field name and schema name.

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 the above two. It populates an associative array with field names and values. The key of the array is the field name and the value of the array is the field id. In most cases, it is more efficient to call this and use the below example for retrieving field id's.

On success: Returns an associative array of all fields in the schema.
On failure: Returns undef.

Example:

      %fields = ars_GetFieldTable($c, "User");
      if(defined($fields{"Login name"}) {
          $id = $fields{"Login name"};
      } else {
          print "Field doesnt exist!\n";
      }

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''. Alternating 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)) || 
            print "submission failed\n";

ars_DeleteEntry(ctrl,schema,entry_id)

This function deletes the entry (row) in the schema matching entry_id.

On success: Returns 0.
On failure: Returns -1.

Example:

      ars_DeleteEntry(ctrl,"Schema01",$entry_id);

ars_GetEntry(ctrl,schema,entry_id,...)

This function returns a list (associative array) of values and field ids for a particular schema and entry id. If you specify any field ids after the entry_id parameter, only the values for those fields will be returned. If no field ids are given after entry_id, then all (fieldid, value) pairs are retrieved.

If the fielid is for a Diary Field, the following bit of code shows how to decode the entries:

      $diaryfield_fid = ars_GetFieldByName($ctrl, $schema, $diaryfield);
      %vals = ars_GetEntry($ctrl, $schema, $entry_id);

      foreach $diary_entry (@{$vals{$diaryfield_fid}}) {
        print "$diary_entry->{timestamp}\t$diary_entry->{user}\n";
        print "$diary_entry->{value}\n";
      }

On success: Returns an associative array. The key of the array is the field id and the value of the array are the values of the fields as retrieved from the server.
On failure: Returns undef.

Example:

      %vals = ars_GetEntry($c, "User", $entry_id);
      print "Login name = ".$vals{"Login name"}."\n";

ars_GetListEntry(ctrl,schema,qualifier,maxRetrieve,...)

This function is used to retrieve the list of entry_id's from the specified schema. The entries are returned as a list (associative array) of (entry_id, short-description) pairs. This function requires a Qualifier. If you wish to retrieve all entries in the schema (upto the maximum you specified) you should load a Qualifier with something like (1 = 1). Optional field ids may be given after maxRetrieve to specify the sorting order. If you specify maxRetrieve = 0 then all of the entries will be returned (or the maximum allow by the server administrator, which ever is less).

Note! The "Short-Description" mentioned above is not the contents of the "short-description" field in the schema. It is, in fact, the contents of the "Query List Fields" for this schema. See List_Entries.pl for an example.

On success: Returns a list (associative array) 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";
      }

To specify a sort, you add the field you wish to sort on to the end of the call and then either 1 or 2 to indicate if you want it sorted in ascending or descending order, respectively.

Example of how to set sorting options:

      $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);

to get a list of all users, sorted based on Login Name.

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.

On success
On failure

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
On failure

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:

``Schema''
``Active_Link''
``Filter''
``Escalation''
``Char_Menu''
``Admin_Ext''

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

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

Assign Structure

Assign Field Structure

Active Link Action Structure

Active Link Macro Structure

Arith Op Assign Structure

Display Structure

Entry List Field Structure

Field Assign Structure

Field Characteristics

Field Limit Structure

Function Assign Structure

Index Structure

Macro Parm Structure

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.

Last Updated: 01/12/96
arsperl@smurfland.cit.buffalo.edu