$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.
@matches = $f->query(-query => scalar string,
-maxhits => scalar string,
-firstretrieve => 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".
$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.
$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.
@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).
$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.
$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.
$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.
$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.
$f->merge(-type => numeric value,
-values => { field1 => value1, ...});
This method allows you to "merge" the given fields/values into
a form. The merge operation is fairly powerful, allowing you
to bypass the usual pattern, "not-null", etc, checks that are
enforced on set() and create() operations. In addition,
the merge() operation allows you to over-write existing entries
(including their diary fields). This call
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. In the future,
this call will also do the right thing for diary fields. Currently,
you need to pass the encoded diary to this
routine. See ars_EncodeDiary.
($value1, ...) = $f->get(-entry => scalar string,
-fields => [ field1, ... ]);
This method allows you to retrieve some (or all, if you don't specify
the -fields 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.
%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.
$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.
$v = value2internal(-field => scalar, -value => value);This is an internal routine used to translate enumeration values into text for a given field.
$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.
$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.