Suites: Helix Design Suite, Helix Data Suite, Required Suite, Standard Suite, AppleScript Types

Helix Data Suite

Helix Data Suite Legacy events for accessing Helix record data. (The CallHelix events)

Commands

Utilize

utilize (verb)[synonyms: callhelix, use ] Command for access to Helix for data manipulation. (from Helix Data Suite)

Description

Legacy Notes: The original CallHelix scripting addition supported just one syntax:

  • CallHelix {parameters} selector (legacy action as number)

CallHelix 2.0 (and Helix Scripting) supported this along with these new forms:

  • CallHelix {parameters} action (legacy action as text)
  • use {parameter list} to (legacy action as text)

Because CallHelix is an anachronism, Helix prefers the use {parameters} to (legacy action as text) syntax. However, macOS 10.9 (Mavericks) has taken ‘use’ for its own purposes, so Helix 6.2.3 changes the primary verb to utilize while still supporting ‘use’ as a synonym, to maintiain compatibilty with scripts written pre-Mavericks. (The new terminology will be displayed automatically.) The synonym ‘callhelix’ is now supported as well. The to parameter now supports ‘action’ as a synonym.

Users familiar with the Helix Scripting syntax should be able to switch from using Helix Scripting as a bridge to Helix to scripting Helix directly using this suite. This legacy implementation of Helix data access is limited in scope. The primary limitation is that there is no mechanism for specifying a query: the default query is always used to restrict data access. The workaround is to post the query parameters into a ‘global’ relation and use an abacus construct to build the query from those stored values.

When the optional "record ids" parameters was not used, Helix Scripting did not return the Record IDs. This is flipped in Helix: Record IDs are always returned unless this parameter is passed with a value of false.

The optional parameter that is used to specify "delimiters" in Helix Scripting is obsolete: it is completely ignored by Helix.

The optional parameter 'target' has been removed. Scripts should now target the appropriate application directly.

Function Syntax

set theResult to utilize list of text ¬
to legacy action ¬
delimiters list of text ¬
record ids boolean

Result

list of anything The specific elements of the reply vary depending on the legacy action.

Parameters

Parameter
Required
Type
Description
direct parameter required list of text Parameter list. The specific elements of the list vary depending on the legacy action.
delimiters optional list of text Specify field and record delimiters (in that order) to use when retrieving data as a list. Ignored: Helix now always determines the delimiters from the view when retrieving records.
record ids optional boolean Return Helix’s internal Record IDs along with the record data. Record IDs are returned by default in the retrieved data record. To suppress Record IDs, pass this as false.
to
[synonyms: action, legacy action]
required legacy action The legacy action to perform. See the list of actions for details.

Classes

Retrieved data record

retrieved data record (noun)An AppleScript record containing data for one Helix record. The Helix record data is in the helix record item, and the internal Record ID (used for deleting records) is in the record id item. Use get helix record of syntax to access the record data. Subform records are returned in discreet records, prefixed with a additional delimiter for each level of subform nesting.

Properties

Property
Access
Type
Description
class get type class The class of the object
item
helix record get textor list of text The user data for the Helix record. The fields are returned as a list or string, depending on which legacy action is specified.
properties get record A record with all the properties of the item.
item
record id get integer The internal RecordID for the Helix record. To delete a record, pass its internal RecordID. Although internal RecordIDs do not change, a record will acquire a new RecordID if it is deleted & recreated via posting or an export/delete/import operation

Superclass

The retrieved data record class inherits elements and properties from item.

Enumerations

Legacy action

legacy action (enumeration)Which of the 17 legacy actions to do.

Constants

Constant
Description
check view state For testing: Use to determine if a view exists and if it is a list. Direct Parameter is {collection, user, password, relation, view, allowsEntry}. Returns nothing. The sixth parameter tests if the view allows entry: if true and the view is a list, error 200 is returned. If false, any legal view returns no error.
close process Terminate an open ProcessID. Direct Parameter is a ProcessID. Returns nothing. Always close a process when you are finished with it. The number of open processes allowed is limited by the application license.
create process for retrieve Open a process for retrieving data in segments from the specified view. Direct Parameter is {collection, user, password, relation, view}. Returns a ProcessID.
create process for store Open a process for store one or more records using the specified view. Direct Parameter is {collection, user, password, relation, view}. Returns a ProcessID.
delete recordID See "delete records"
delete recordIDs Using a previously acquired ProcessID, delete one or more records from the collection, using the view specified when the ProcessID was requested. Direct Parameter is {ProcessID, RecordID, [RecordID, ]} The number of RecordIDs that can be sent in one event statement is limited by a preference setting. Returns integer count of records deleted. RecordIDs are acquired when retrieving data.
get partial view data Using a previously acquired ProcessID, retrieve a range of records from the view specified when the ProcessID was requested. Direct parameter is {ProcessID, [Start Record], [How Many To Get], [Indent Subform Records]}. Returns one or more retrieved data records. Start Record is the zero-count ordinal record number of the first record to get. How Many To Get is the number of records to get. Indent Subform Records (a boolean, default is true) controls whether leading field delimiters are used to indicate subform records. See get view data as list for returned data format.
get view data as Helix data Deprecated. Using a previously acquired ProcessID, retrieve a subset of records from the view specified when the ProcessID was requested. See get view data as string for direct parameter details. Returns an AppleScript list of records in legacy (CallHelix 1.x) format.
get view data as list Using a previously acquired ProcessID, retrieve a subset of records from the view specified when the ProcessID was requested. See get view data as string for direct parameter format. See retrieve records as list for returned data format. Set Indent Subform Records to false to suppress list item prefixing.
get view data as string Using a previously acquired ProcessID, retrieve a subset of records from the view specified when the ProcessID was requested. Direct parameter is {ProcessID, DataType} when DataType is 0 (Icon Names) or 1 (Header Data); {ProcessID, DataType, Start Record, How Many To Get, [Indent Subform Records]} when DataType is 2 (Record Data). See retrieve records as string for returned data format. Set Indent Subform Records to false to suppress delimiter prefixing.
get view summary After a ProcessID is requested, delay until the specified view is ready. (Optimized views reduce delays.) Direct parameter is {ProcessID}. Returns a process ready record containing {record count, field delimiter, record delimiter}.
retrieve records as list Get every record on the specified view. Direct parameter is {collection, user, password, relation, view}. Returns an AppleScript list of Helix records. Field data is returned as an AppleScript list. Subform records are returned as discreet records, prefixed with an additional empty list item for each level of subform nesting.
retrieve records as string Get every record on the specified view. Direct parameter is {collection, user, password, relation, view}. Returns an AppleScript list of Helix records. Field data is returned as a string with field and record delimiters included. Subform records are returned as discreet records, prefixed with an additional field delimiter for each level of subform nesting.
store one record Store a text string (with embedded field delimiters) in Helix. Direct parameter is {collection, user, password, relation, view, record data}. See store records for returned data format. Data that fails validation or type checking results in error 1000.
store record See store records
store records Using a previously acquired ProcessID, store one or more records in the view specified when the ProcessID was requested. Direct parameter is {ProcessID, record data, [record data, ]} Each record data parameter is a text string (with embedded field delimiters) to be stored as a record. The number of RecordIDs that can be sent in one event statement is limited by a preference setting. Returns a list of flags indicating success/failure for each attempt.
test view for readiness Deprecated: Use get view summary instead.

Where Used

The legacy action enumeration is used in the following ways:

to parameter of the utilize

Records

Process ready record

process ready record (record)Record type returned by the get view summary legacy action.

Properties

Property
Access
Type
Description
field delimiters get text The delimiter inserted between fields returned by the view. (Specified in Helix RADE)
record count get integer The number of records available from the specified view. (The default query for the view is used.)
record delimiters get text The delimiter inserted between records returned by the view. (Specified in Helix RADE)