ARSperl: Usage

## Using the ARS Perl extension

### Note

This documentation is under construction.

### Contents

- Loading the extension
- Reserved variables
  - ars_errstr
- Functions overview
  - ars_Login
  - ars_Logoff
  - ars_LoadQualifier
  - ars_GetListField
  - ars_GetListEntry
  - ars_GetListSchema
  - ars_GetListServer
  - ars_GetListActiveLink
  - ars_GetListFilter
  - ars_GetListCharMenu
  - ars_GetListEscalation
  - ars_GetListAdminExtension
  - ars_Export
  - ars_GetActiveLink
  - ars_GetCharMenuItems
  - ars_GetFieldByName
  - ars_GetFieldTable
  - ars_GetEntry
  - ars_GetField
  - ars_GetSchema
  - ars_SetEntry
  - ars_CreateEntry
  - ars_DeleteEntry
- 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

  #### 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