ARSperl Manual - OO Layer Overview

# ARSperl Programmer's Manual - OO Layer Form Object

## Methods

constructor

      $f = new ARS::form(-form => scalar string,
                         -vui  => scalar string,
                         -connection => ARS object);

This is the default constructor. To make life easier, you should use the openForm() method available in the Connection Object.

destructor Currently, the form destructor does nothing.

query()

      @matches =  $f->query(-qualifier => scalar string,
                            -maxhits   => scalar string);

This function allows you to run a query against a Form. Both parameters are optional. If you specify neither, you will get a list of all available records upto the limit imposed on the server. If you specify a qualifier and a maxhits number, you will get matching records upto the maximum number of hits you specified.

This method returns a list of matching Record IDs. It does not currently return a "query list".

getFieldID()

      $id = $f->getFieldID(-field => scalar string);

This an "internal" function that is used to translate a field name to a field ID. Eventually, it will obey the VUI you specified.

getFieldName()

      $name = $f->getFieldName(-id => scalar string);

This an "internal" function that is used to translate a field ID to a field nameD. Eventually, it will obey the VUI you specified.

getEnumValues()

      @vals = $f->getEnumValues(-field => scalar string);

This function returns a list of enumeration values (labels) for a given field. If the field is not an enumeration field, an exception is thrown (type=ERROR, num=81006).

getFieldType()

      $type = $f->getFieldType(-name => scalar string,
                               -id => scalar string);

This an "internal" function that is used to retrieve the datatype of a particular field. You must specify one of the parameters. If you specify both, the -id parameter is ignore in favor of the -name parameer. Eventually, it will obey the VUI you specified.

create()

      $id = $f->create(-values => { field1 => value1, ... });

This function allows you to create a new entry in this form. You can specify field name to field value mappings with out regard for the field ID or enumeration types. Behind the scenes magic occurs to hide this from you.

Eventually, it will obey the VUI you specified.

In order to create an entry with an attachment, you should use the following format:

      $id = $f->create(-values => {
                   "Attachment Field Name" => { file => scalar filename,
                                                OR
                                                buffer => scalar,
                                                AND
                                                size => scalar
                                              }
                                  });

Note that the size field must correspond to either the length of the in-core buffer or the size of the file you wish to attach. Specifying and incorrect length will result in a truncated attachment. See the `t/entry.t` file in the source distribution for an example of adding attachments to records.

delete()

       $f->delete(-entry => scalar string);

This method will delete a given entry from the form. It does not "pad out" the entry id for you currently. So if there are leading zeros, you must add them.

set()

       $f->set(-entry => scalar string,
               -gettime => scalar timestamp,
               -value => { field1 => value1, ...});

This method allows you to set the field values of an existing entry. It currently does not obey the VUI setting. You may specify the enumeration field text instead of the enumeration value. In the future, you will have the option of specifying either.

get()

       ($value1, ...) = $f->get(-entry => scalar string,
                                -fields => [ field1, ... ]);

This method allows you to retrieve some (or all, if you don't specify the -value parameter) fields for a given record ID from the form. It does not currently obey the VUI setting. In addition, you can not specify field ID's currently, but will be able to in the future. Finally, the entry ID will not be padded out for you currently. In addition, enumeration values will be converted on the fly for you.

getAsHash()

       %h = $f->getAsHash(-entry => scalar string,
                          -fields => [ field1, ... ]);

This method is identical to get() in every way except for the return value. This method returns a list of key/value pairs where the key is the field name (currently doesn't obey vui setting) and the field value (enumeration values are converted to text automatically).

The current implementation does allow for the specification of sort order, but in the future it will and then you should, as usual, put the return value into an array instead of a hash.

getAttachment()

       $v = $f->getAttachment(-entry => scalar string,
                              -field => [ field1 ],
                              -file  => scalar string);

This method allows you to retrieve an attachment from the given record. You must specify both the record's entry ID and the attachment field name. The `file` parameter is optional. If specified, the attachment will be written to the given filename. If not specified, the attachment is returned as a scalar value.

value2internal()

      $v = value2internal(-field => scalar, -value => value);

This is an internal routine used to translate enumeration values into text for a given field.

internal2value()

      $v = internal2value(-field => scalar, -id => scalar, -value => value);

This is an internal routine used to translate enumeration text into enumeration values for a given field. You must specify either the field or id parameter as well as the value parameter.

setSort()

      $f->setSort("Field Name1", [ARS::AR_SORT_ASCENDING or ARS::AR_SORT_DESCENDING],
                  "Field Name2", [ARS::AR_SORT_ASCENDING or ARS::AR_SORT_DESCENDING],
                  ...);

This method allows you to set the sort option (ascending or descending) for field names. Each field name must be followed by a sort option. The fields will be sorted in the order they are listed in the parameter list.

Back to Table of Contents
Last updated 9 Jun 1999 by jcmurphy@buffalo.edu.