ARSperl: Usage

## Using the ARS Perl extension

$Id: usage.html,v 1.7 1997/02/03 18:34:49 jmurphy Exp $

### 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
  - ars_GetFilter
  - ars_GetCharMenu
  - ars_GetServerStatistics
  - ars_GetProfileInfo
- 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)`
  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_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.

  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:

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

`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
  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.

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