skip to main content
OpenEdge Development: ADM Reference
Data Objects and Their Methods and Properties : Base methods for data objects
 
Base methods for data objects
This section lists and describes the methods for all data objects.
addForeignKey
This function assigns the ForeignKey to the query string. The ForeignKey consists of ForeignKeys and ForeignValues.
Location: dataquery.p
Parameters: None
Returns: LOGICAL
Notes: None
assignQuerySelection
This function assigns selection criteria for a query. The function distributes column/value pairs to the corresponding buffer’s WHERE clause. Each buffer’s expression is enclosed in parenthesis.
Location: dataquery.p
Parameters:  
INPUT pcColumns AS CHARACTER
A comma‑separated list of column names. The column names can be in the following forms:
*tablename.fieldname
*database.tablename.fieldname (Should be used only if “Qualified with database” is specified.)
*RowObject.fieldname for SDOs.
*If unqualified fieldnames are passed in, the function checks the Tables property and assumes the first table with a match is the correct table.
INPUT pcValues AS CHARACTER
A CHR(1)‑separated list of the corresponding values.
INPUT pcOperators AS CHARACTER
A comma‑separated list of the operator for each column/value (one for all columns). A blank defaults to (EQ). A slash defines an alternative string operator (EQ/BEGINS, and so forth).
Returns: LOGICAL
Notes:  
*This procedure can be called before initialization. However, because the data type is unknown, the alternative string operator is not supported before the object is initialized.
*This procedure is designed to be called multiple times. This design lets you build up the query’s WHERE clause by storing intermediate results in the QueryString property before it is finally used in a Query–Prepare method.
*Uses openQuery to prepare the QueryString property.
*The QueryColumns property ensures that each column and operator is added only once to the QueryString. The property also stores the offset and length of the corresponding values.
confirmCommit
This procedure checks the state of all data-targets to see if it is alright to commit. The transaction should not be committed if a data-target is modified or the RowUpdateState is 'rowUpdated'. If there are unsaved changes, the I-O parameter returns TRUE. In this case, the visual objects (visual.p) offer the user the opportunity to save or cancel a record to proceed with the commit process.
Location: dataquery.p
Parameters:  
INPUT-OUTPUT pioCancel AS LOGICAL
Returns TRUE if the transaction should not be committed.
Notes: None
confirmContinue
This procedure asks all data-targets whether they have changes pending.
Location: dataquery.p
Parameters:  
INPUT-OUTPUT pioCancel AS LOGICAL
Returns TRUE if any data-target reports a pending change.
Returns: LOGICAL
Notes:  
*If any data-target reports a pending change, this routine returns pioCancel = TRUE to its caller. The caller then must handle the discrepancy, typically by reporting the unsaved changes to the user and requesting disposition instructions (Save, Discard, etc.).
*Call this procedure from any method that might change the result set somewhere in the data-source chain, like openQuery or navigation actions.
*This procedure is called from the filter-source to see if new criteria can be applied.
*The standard behavior in the ADM disables navigation when there are pending changes. If you have enabled navigation, you can call this procedure from the fetch* methods to check for pending changes.
confirmUndo
This procedure, if called with a FALSE argument, publishes confirmUndo all data-targets to determine whether any are Modified or in AddMode. The procedure returns TRUE if the undo should be cancelled. The visual objects (visual.p) warn the user that unsaved changes will be cancelled.
Location: dataquery.p
Parameters:  
INPUT-OUTPUT pioCancel AS LOGICAL
Returns TRUE if the commit should not continue.
Note: If called with a TRUE argument, the routine does nothing.
exportData
This procedure exports the contents of a data object to an external tool.
Location: dataquery.p
Parameters:  
INPUT pcExportType AS CHARACTER
The target tool of the export. Valid values are Excel and Crystal.
INPUT pcFieldList AS CHARACTER
Either a list of input fields (visible fields only) or leave blank for all (no table prefix).
INPUT plIncludeObj AS LOGICAL
Indicates whether or not the input should include object fields. The options available are Yes or No.
INPUT plUseExisting AS LOGICAL
Indicates whether to use a currently active instance of the target tool. (Currently supported for Excel only). The available options are Yes or No.
INPUT piMaxRecords AS INTEGERINPUT
Maximum number of records to process. Passing the Unknown value (?) is the signal to prompt for the maximum records and whether to return all fields or just the displayed fields. This ensures backwards compatibility if anyone uses the old style of asking before calling printToExcel in a SDO.
Notes:  
*When this procedure is inherited by the Data class, it always excludes RowObject specific fields. For example, RowNum, RowIndent, RowMod.
*The external tool's exportData procedure does a call back to the data object’s tableout procedure for the actual retrieval of the data.
filterContainerHandler
This procedure adds a Filter link between a Filter container handler and a Filter container. This procedure is called from startFilter after the Filter container is constructed.
Location: dataquery.p
Parameters:  
phFilterContainer AS HANDLE
Handle of the Filter container.
Note: The code to add the Filter link has been separated from startFilter to enable overriding of this procedure to add other links between this object and the Filter container.
findRow
This function finds a row and repositions to it using the key.
Location: dataquery.p
INPUT pcKeyValues AS CHARACTER
Comma- or CHR(1)-separated list of keyfields.
Returns: LOGICAL
Note: This method resolves the row reposition on the server. As a result, the data object cannot determine whether the row position is invalid until after the request has been executed. If the RebuildOnRepos property is set to TRUE, the temp-table is emptied before the request.
indexInformation
This function returns a CHR(1)-separated list of index information for all buffers in the query. You can specify whether or not the fieldnames are qualified with the tablename (and database if appropriate). If the fieldnames are not qualified, CHR(2) is used as a table separator.
Location: dataquery.p
Parameters:  
INPUT pcQuery AS CHARACTER
The type of index information to return. You can specify different information for each buffer by adding the buffer number in parenthesis to the type, for example, 'Primary(1)'. Valid values are:
*'All' — All indexed fields.
*'Standard' or '' — All indexed fields excluding word indexes.
*'Word' — Word-indexed indexes.
*'Unique' — Unique indexes.
*'NonUnique' — Non-unique indexes.
*'Primary' — Primary index.
*'Info' — All information. This is meaningless if pcIndexInfo is not the Unknown value (?).
INPUT plUseTableSep AS LOGICAL
Whether to use the table separator. If YES, the separator is used. If NO, the separator is not used. If this is NO and pcIndexInfo is the Unknown value (?), fieldnames are qualified. Otherwise, they are as specified in pcIndexInfo.
INPUT pcIndexInfo AS CHARACTER
Previously retrieved index information in the exact format returned from this function using indexInformation('info',yes,?). This enables you to use the function without a database connection.
Returns: CHARACTER
Note: The parameter enables the function to be used without a database connection.
insertExpression
This function inserts an expression into a single buffer’s WHERE clause.
Location: dataquery.p
Parameters:  
INPUT pcWhere AS CHARACTER
Complete WHERE clause with or without the FOR keyword, but without commas.
INPUT pcExpression AS CHARACTER
New expression or OF phrase (Existing OF phrase is replaced).
INPUT pcAndOr AS CHARACTER
Specifies what operator is used to add the new expression to existing ones, either AND (the default) or OR.
Returns: CHARACTER (PRIVATE)
Notes:  
*The new expression is embedded in parentheses, but no parentheses are placed around the existing expression.
*Lock keywords must be unabbreviated or without –LOCK (for example, SHARE or EXCLUSIVE).
*Any keyword in comments might cause problems.
isUpdateActive
This procedure is published from the container source through the container link to check whether contained objects have unsaved or uncommitted changes. This includes objects in addMode.
Location: dataquery.p
Parameters:  
INPUT-OUTPUT plActive AS LOGICAL
FALSE if the ContainerTargets should be surveyed.
Notes:  
*This procedure is published through the container link from canExit for close logic (OK, Cancel, Exit). It is very similar to how canNavigate and isUpdatePending interact through the data link.
*This procedure only checks rowObjectState as the other states are checked in the visual objects.
isUpdatePending
This procedure publishes to data-targets to check pending updates. It returns TRUE and stops publishing if there is a pending update.
Location: dataquery.p
Parameters:  
INPUT-OUTPUT plUpdate AS LOGICAL
Whether or not there are pending updates.
Notes:  
*New is included as a pending update.
*Called from canNavigate, which is used by navigating objects to check if they can trust an updateState('updateComplete') message.
*This check is ONLY valid from a dataSource point of view. Use canNavigate to check an actual object.
linkState
This procedure receives the state of the link from the publisher. It uses that information to decide whether or not to disable the link.
Location: dataquery.p
Parameters:  
INPUT pcState AS CHARACTER
The link state of the publisher. This can be active or inactive. These states correspond to whether or not a visual object is hidden.
Notes:  
*The received event is republished up the groupAssignSource and the dataSource.
*When the object cannot respond to an ‘inactive’ message, it must not republish the event to its data-source. However, the LinkState is needed for other types of links like the NavigationSource. This conflict is solved by republishing the event with a different modifier, such as ‘inactive-target’. The data-source can then ignore it while the NavigatonSource still can react to it.
*The logic is separated into processLinkState to allow the Data class to override this without duplicating all logic.
newQueryString
This function returns a new query string to the passed query. The tables in the passed query must match with the getTables function. This function adds column/value pairs to the corresponding buffer’s WHERE clause. Each buffer’s expression is always embedded in parentheses.
Location: dataquery.p
Parameters:  
INPUT pcColumns AS CHARACTER
A comma‑separated list of column names of a table in the query. The column names can be in the following forms:
*tablename.fieldname
*database.tablename.fieldname (Should be used only if “Qualified with database” is specified.)
*RowObject.fieldname for SDOs.
*If unqualified fieldnames are passed in, the function checks the Tables property and assumes the first table with a match is the correct table.
INPUT pcValues AS CHARACTER
A CHR(1)-separated list of corresponding values for the columns.
INPUT pcOperators AS CHARACTER
A comma‑separated list of the operator for each column/value (one for all columns). A blank defaults to (EQ). A slash defines an alternative string operator (EQ/BEGINS, and so forth).
INPUT pcQueryString AS CHARACTER
A complete, qualified query string matching the queries tables. The Unknown value (?) means use the existing query.
INPUT pcAndOr AS CHARACTER
How to append each new expression to the passed query. You can specify AND or OR for each buffer.
Returns: CHARACTER
Notes:  
*This procedure can be called before initialization. However, because the data type is unknown, the alternative string operator is not supported before the object is initialized.
*This function operates like assignQuerySelection without the replace functionality.
newWhereClause
This function inserts a new expression to a specified buffer’s WHERE clause.
Location: dataquery.p
Parameters:  
INPUT pcBuffer AS CHARACTER
The buffer.
INPUT pcExpression AS CHARACTER
The new expression.
INPUT pcWhere AS CHARACTER
The current query prepare string.
INPUT pcAndOr AS CHARACTER
Specifies what operator is used to add the new expression to existing expressions, either AND (the default) or OR.
Returns: CHARACTER
Note: This is supported as a utility function that does not use any properties. However, if the target procedure is the super procedure, the qualifications of the passed buffer and the query must match. If the target procedure is not the super procedure, the buffer is corrected if it exists in the object’s query. Otherwise, it must match.
printToCrystal
This procedure transfers the data from the data object to Crystal Reports.
Location: dataquery.p
Parameters:  
INPUT pcFieldList AS CHARACTER
The list of fields to be transferred, or the empty string to mean ‘all’. Do not include the table prefix.
INPUT plIncludeObj AS LOGICAL
TRUE if object fields are to be included.
INPUT piMaxRecords AS INTEGER
The maximum number of records to transfer.
Note: Because this procedure makes use of tableOut, always excludes rowobject specific fields, for example, RowNum, RowIdent, and RowMod.
removeForeignKey
This function removes the ForeignKey from the query string.
Location: dataquery.p
Parameters: None
Returns: LOGICAL
Note: The ForeignKey consists of ForeignKeys and ForeignValues.
removeQuerySelection
This function removes field expressions criteria for specified columns and operators from the query that were added by assignQuerySelection.
Location: dataquery.p
Parameters:  
INPUT pcColumns AS CHARACTER
A comma-separated list of column names in the phrase to be removed.
INPUT pcOperators AS CHARACTER
A comma‑separated list of the operator for each column/value (one for all columns). A blank defaults to (EQ). A slash defines an alternative string operator (EQ/BEGINS, and so forth).
Returns: LOGICAL
Note: This procedure modifies the QueryString property. The openQuery function prepares the query using the QueryString property. The removal of the expression is done using the value of the position and length stored in the QueryColumns property.
resetQueryString
This function removes all filter and sort criteria from the QueryString.
Location: dataquery.p
Parameters: None
Returns: LOGICAL
Notes: None
resolveColumn
This function resolves a column reference for query manipulation APIs.
Location: dataquery.p
Parameters:  
INPUT pcColumn AS CHARACTER
The column to resolve.
Returns: CHARACTER
Note: The function qualifies unqualified columns or replaces a RowObject qualifier with the DataTable.
rowAvailable
This function checks RowObject availability. It encapsulates the different query position alternatives required to check for availability.
Location: dataquery.p
Parameters:  
INPUT pcDirection AS CHARACTER
Indicates the direction to check for a record. The valid values are:
*NEXT — Is there a next record available?
*PREV — Is there a previous record available?
*' ', Unknown value (?), or CURRENT — The current record.
Returns: LOGICAL
Note: This can be used in loops to simplify logic when navigating.
rowValues
This function retrieves a list of data from all rows in the data object.
Location: dataquery.p
Parameters:  
INPUT pcColumns AS CHARACTER
Comma-separated list of RowObject column names.
INPUT pcFormat AS CHARACTER
The following formatting options available for the data:
*blank or the Unknown value (?) — Unformatted, as from columnValue.
*Formatted — Formatted without trailing blanks.
*TrimNumeric — Formatted without leading spaces for numeric data (left justified).
*NoTrim — Formatted with leading and trailing blanks.
*&n A free form format. The number references the column in pcColumns order and indicates that the column values should be substituted as specified instead of returned as delimiter-separated values.
This allows formatting data to be mixed with the returned values. For example, '&2 (&1)', '&2 / &1' and so on. To build a list-item-pair list, you must ensure that the delimiter is in the format. For example, '&2 (&1)' + ',' + '&1' where ',' is also passed as a delimiter and would return a paired list where the second item of the pair is column number one.
INPUT pcDelimiter AS CHARACTER
A single character delimiter. The Unknown value (?) defaults to CHR(1). A blank defaults to a single space.
Returns: CHARACTER
Notes:  
*This function is intended for use by SmartSelect or other nonbrowser objects that need to show all rows of the data object.
*This function should not be used with large amounts of data since all data needs to fit in the return value.
*A maximum of nine columns can be passed when a substitute format is specified.
*This function reads all data without publishing dataAvailable to its data-targets. However, if the query is browsed, dataAvailable publishes to its data-targets when reposition-to-rowid is executed to return to the current record.
sortExpression
This function returns the sort expression of the passed QueryString.
Location: dataquery.p
Parameters:  
INPUT pcQueryString AS CHARACTER
The QueryString for which to find the sort expression.
Returns: CHARACTER
Note: Unlike the getQuerySort function, the returned string includes the first BY keyword and removes extra spaces.
startFilter
This procedure views, starts, or both views and starts the linked filter-source.
Location: dataquery.p
Parameters: None
Note: This procedure uses filterContainerHandle to add the Filter link between the object and the Filter container.
tableOut
This procedure outputs requested fields from the data object to a standard temp-table format.
Location: dataquery.p
Parameters:  
INPUT pcFieldList AS CHARACTER
The list of fields wanted. Do not use a table prefix.
INPUT plIncludeObj AS LOGICAL
Whether to include object fields.
INPUT piMaxRecords AS INTEGER
Maximum number of records to handle.
OUTPUT TABLE FOR ttTable
The data object data.
OUTPUT iExtractedRecs AS INTEGER
The actual number of records handled.
Notes:  
*Temp-table is defined in afttsdoout.i. Fields passed in are checked with a CAN-DO to support * for all or ! field_name to exclude a field, for example,
!RowNum,!RowIdent,!RowMod, * would use all non-data object specific fields.
*The temp-table contains a record for each record/field combination.
transferToExcel
Procedure transfers the contents of the data object to Microsoft Excel.
Location: dataquery.p
Parameters:  
INPUT pcFieldList AS CHARACTER
The list of fields to be transferred. Do not use the table prefix.
INPUT plIncludeObj AS LOGICAL
Whether to include object fields.
INPUT plUseExisting AS LOGICAL
Whether to use the currently-running copy of Excel.
INPUT piMaxRecords AS INTEGER
Maximum number of records to transfer.
Note: Because this procedure makes use of tableOut, always excludes rowobject specific fields, for example, RowNum, RowIdent, and RowMod.
updateQueryPosition
This procedure resets the QueryPosition property after a record navigation. This function eliminates duplication, eliminates errors, and minimizes messaging (published by setQueryPosition) in fetchFirst, fetchPrev, fetchNext, and fetchLast.
Location: dataquery.p
Parameters: None
Notes:  
*data.p should update the LastRowNum, FirstRowNum, and LastDbRowIdent properties and then call this function.
*The LastRowNum and FirstRowNum properties store the RowObject.RowNum of the first and last record in the data provider.
updateState
This procedure passes along update-related messages (to its Navigation–Source, for example) and adjusts the DataModified property.
Location: dataquery.p
Parameters:  
INPUT pcState AS CHARACTER
The state of an updatable record. Valid values are:
*UpdateBegin — The user has indicated that an update can take place, either by pressing the Update button in a panel or by entering an updatable field in a browser.
*Update — An update is in progress in another object (a viewer or browser).
*UpdateEnd — A save has completed (the same as UpdateComplete.)
*UpdateComplete — Any changes to the RowObject temp-table have been either committed or backed out.
Notes:  
*The data object also saves its own copy of the DataModified property. The property is set TRUE when updateState is Update and set FALSE when updateState is UpdateComplete, so that it can be queried by other objects (such as other Data–Targets).
*For visual objects, the updateState is both a DataSourceEvent and DataTargetEvent. To avoid bouncing messages back to the dataTargets that are both subscribers and publishers, we set the CurrentUpdateSource so the DataTarget can avoid republishing the event.