skip to main content
OpenEdge Development: ADM Reference
Data Objects and Their Methods and Properties : Methods for query objects
 
Methods for query objects
This section lists and describes the methods for query objects.
addNotFoundMessage
Function that adds an error message for a record not found based on keys and values using the same format as findRowWhere and other query functions.
Location: query.p
Parameters:  
INPUT pcFields AS CHAR
Comma-separated list of column names.
INPUT pcValues AS CHAR
CHR(1)-separated list of corresponding values.
Note: The message is for unique finds.
addQueryWhere
Function that adds string-expressions to the query’s WHERE clause and stores the result in the QueryString property. The function returns TRUE if successful, FA LSE if an appropriate buffer name for the WHERE-clause cannot be located.
Location: query.p
Parameters:  
INPUT pcWhere AS CHARACTER
Expression to add (might also be an “OF” phrase).
INPUT pcBuffer AS CHARACTER
An optional buffer specification.
INPUT pcAndOr AS CHARACTER
Specifies the operator that is used to add the new expression to an existing expression or expressions, either AND (the default) or OR.
Returns: LOGICAL
Notes:  
*Returns FALSE if it cannot find a buffer name to associate with the WHERE clause.
*This procedure is designed to run on the client so that it can be called multiple times. This design lets you add multiple phrases to the where-clause before the full where-clause is used to reopen the query.
assignDBRow
Procedure that modifies values copied from the RowObject row to the database records (which for an Update have already been retrieved and locked).
Location: query.p
Parameters:  
INPUT phRowObjUpd AS HANDLE
Handle of the buffer from which to copy.
Notes:  
*The SmartDatatObject determines which fields to save to the database tables based on a comparison of the before-image and the changed record.
*The RowObjUpd.ChangedFields that was used for this purpose is now obsolete.
*The procedure copies over only those fields whose values were actually modified. If this is a copied record, all the fields that were enabled for update are saved.
*If the RowMod field is A for Add or C for Copy, the procedure creates the database records first and then does the assign.
batchServices
A procedure that groups a sequence of SmartDataObject service requests into a single request and thereby minimizes network messaging and improves performance.
Location: query.p
Parameters:  
INPUT pcServices AS CHARACTER
A CHR(1)‑separated list of SmartDataObject internal procedures and functions to be executed. Each entry consists of a CHR(2)‑separated list of INPUT PARAMETER values with the first entry being the NAME of the procedure or function to be executed.
OUTPUT pcValues AS CHARACTER
A CHR(1)‑separated list of CHR(2)‑separated strings of output values that result from the execution of the services listed in pcServices (above). There is a one‑to‑one correspondence between the CHR(1)‑separated list of Services in pcServices (above) and the CHR(1)‑separated list in pcValues. Procedures with no output parameters have a NULL entry. The return values of functions appear as the first entry of the corresponding CHR(2)‑separated list, followed by any output parameters.
Note: batchServices supports only a limited list of services. This list consists of all get and set functions that do not require processing other than getting and setting the property in the ADMProps temp-table record as well as columnProps, initializeObject, openQuery, and synchronizeProperties. The list of cases is extended from release to release. Developers can extend the list by overriding batchServices with a local version that has an extended list then running SUPER.
bufferCopyDBToRO
Procedure that performs a BUFFER–COPY of a database buffer to a row object buffer. In particular, if an assign–list is used to map individual array elements from the database buffer to the row object buffer, this procedure ensures that the values are copied properly.
Location: query.p
Parameters:  
INPUT phRowObj AS HANDLE
Handle to the row object buffer that is to be the target of the BUFFER–COPY.
INPUT phBuffer AS HANDLE
Handle to the database buffer that is to be the source of the BUFFER–COPY.
INPUT pcExcludes AS CHARACTER
Comma‑separated list of fields to be excluded from the BUFFER–COPY.
INPUT pcAssigns AS CHARACTER
Comma‑separated list of field pairs to be individually copied. The field pairs are mappings of fields from the target/source buffers where the field names differ.
Note: The primary purpose of this procedure is to detect when individual array fields are referenced in the assign–list (pcAssigns) from the database buffer and to ensure that they are copied properly. It is assumed that the database buffer is always the source of the BUFFER–COPY, so that the second field in the assign–list field pair is always where the individual array reference is found (for example, pcAssigns = “ROfld1,DBfld[1]”).
ColumnPhysicalColumn
Function that returns the qualified physical name ([DB.]TBL.FLDNM) mapped to the RowObject column specified in pcColumn.
Location: query.p
Parameters:  
INPUT pcColumn AS CHAR
Rowobject name to look up.
Returns: CHARACTER
Notes: None
ColumnPhysicalTable
Function that returns [dbname.]table of a rowobject or database column.
Location: query.p
Parameters:  
INPUT pcColumn AS CHAR
Database fieldname. Can be in the form of: DB.TBL.FLDNM, TBL.FLDNM or FLDNM. If not qualified, the FIRST reference in query is used).
Returns: CHARACTER
Notes:  
*Used to ensure and fix a column reference according to the query's use of database qualification. See dbColumnHandle for additional information.
*Supports a pcColumn specified with brackets.
closeQuery
This function closes the database query.
Location: query.p
Parameters: None
Returns: LOGICAL
Note: In a split SDO, there is no database query to close on the client side. Therefore, executing closeQuery on the client side of a split SDO does nothing.
colValues
This function formats into character strings (using the field format specification) a row of values from the current row of the database Query for the specified column list.
Location: query.p
Parameters:  
INPUT pcViewColLis AS CHARACTER
A comma‑separated list of column names whose values are to be returned.
Returns: CHARACTER
Note: Passes back a CHR(1)‑separated list of formatted values preceded by the RowIdent code (a comma‑separated list of rowids of the database records from which the row is derived) as the first value in all cases.
createObjects
This procedure defines the temp-tables for a dynamic SDO.
Location: query.p
Parameters: None
Notes: None
dataAvailable
This event procedure generates a dependent query dynamically based on the ForeignFields property. This event occurs when dataAvailable is published by a data source because the data source has been repositioned to a different row in its query and this has an impact on dependent objects.
Location: query.p
Parameters:  
INPUT pcRelative AS CHARACTER
Provides information about a newly available record. Valid entries are:
*SAME — The current record is being resent because it has been updated. This procedure ignores this value.
*VALUE–CHANGED — A target SDO has changed its query position. This procedure needs to set the QueryPosition property then change pcRelative to DIFFERENT before passing it to other target procedures so that it appears as though the change occurred in this procedure.
*RESET — Resets the status and foreign fields, and refreshes visual objects and panels for all objects that are part of the data link. This option provides more functionality than SAME and less functionality that DIFFERENT. Use this option when you want to send notification about a change in the RowObject record without having to reopen all the dependent queries.
*DIFFERENT — Values for foreign fields should be reapplied.
*FIRST, NEXT, PREV, LAST— Treated the same as DIFFERENT in this version of dataAvailable.
*TRANSFER — Joins the child data object to the current record in a parent data object. As a result, the call only needs to be performed in the parent data object inside of a container.
Note: This version of dataAvailable is for SDOs that depend on another SDO. The code is different from that for a Viewer. If there are no foreign fields, then this procedure is run when a target is repositioned (usually a SmartDataBrowser). In this case, just the event is passed on to other targets.
dbColumnDataName
Returns the RowObject field name of a database field name.
Location: query.p
Parameters:  
INPUT pcDbColumn AS CHARACTER
A qualified database field name. It must be in the form DataBase.Table.FieldName, or the form Table.FieldName.
Returns: CHARACTER
Note: The passed fieldname must match the SmartDataObject’s definition in regards to qualifying with database name or not.
dbColumnHandle
Returns the handle of a database column.
Location: query.p
Parameters:  
INPUT pcColumn AS CHARACTER
The column whose handle is wanted. Can be unqualified (column), partly qualified (table.column), or fully qualified (database.table.column). If not fully qualified, the first match is returned.
Returns: HANDLE
Note: Is capable of processing a pcColumn specified with brackets. Used by columnDataType, ColumnValMsg, and ColumnTable.
defineDataObject
Function used to define the following Progress Dynamics data object properties:
*Tables
*BaseQuery
*DataColumns
*DataColumsByTable
*UpdatableColumnsByTable
*AssignList
Location: query.p
Parameters:  
INPUT pcTableList AS CHARACTER
Comma-separated list of tables. If the table names are database qualified then the column list also needs to be database qualified.
INPUT pcBaseQuery AS CHARACTER
Query used for the dynamic SmartDataObject.
INPUT pcColumnList AS CHARACTER
Comma-separated list of qualified columns in the format: TableName.ColumnName[.RemanedColmnName]. Where TableName is the database table name, ColumnName is the field name, and RenamedColumnName is the renamed field name. This parameter is optional.
INPUT pcUpdatableColumns AS CHARACTER
Comma-separated list of logical values with special cases such as YES, NO, or a combination of YES,NO,YES,NO. If the value is:
*YES — All the columns are updatable.
*NO — All the columns are not updatable.
*YES,NO,YES,YES — The individual columns have the specified value.
Returns: LOGICAL
Notes: None.
deleteRecordStatic
Deletes a record from the specified table in the query.
Location: query.i
Parameters:  
INPUT piTableIndex AS INTEGER
Returns: LOGICAL
Note: This function is necessary in order to work around a limitation with the BUFFER-DELETE( ) method for buffer handles. The method fails if there is delete validation defined on the target table. The workaround is to use a static “DELETE {table}.” statement instead.
destroyObject
This procedure cleans up and deletes the object and its contained objects.
Location: query.p
Parameters: None
Notes: None
fetchFirst
This procedure repositions the database query to the first row.
Location: query.p
Parameters: None
Note: The procedure requests rows to be transferred from the database query if the RowObject query is empty.
fetchLast
This procedure repositions the database query to the last row.
Location: query.p
Parameters: None
Notes: None
fetchNext
This procedure repositions the database query to the next row.
Location: query.p
Parameters: None
Notes: None
fetchPrev
This procedure repositions the database query to the previous row.
Location: query.p
Parameters: None
Notes: None
fetchCurrentBatch
Reads the current batch of the data object.
Location: query.p
Parameters: None
Notes: None
fetchFirstBatch
Procedure that reads the first batch of the data object.
Location: query.p
Parameters: None
Notes: None
fetchLastBatch
Procedure that reads the last batch of the data object.
Location: query.p
Parameters: None
Notes: None
fetchNextBatch
Procedure that reads the next batch of the data object but does not fill the batch at the end.
Location: query.p
Parameters: None
Notes: None
fetchPrevBatch
Procedure that reads the next batch of the data object and fills the batch at the beginning.
Location: query.p
Parameters: None
Notes: None
firstBufferName
Returns the first buffer reference in a where-clause expression.
Location: query.p
Parameters:  
INPUT pcExpression AS CHARACTER
A string expression.
Returns: CHARACTER PRIVATE
Note: In order to be recognized as a buffer name, it must contain at least one ".", otherwise the return value is the Unknown value (?).
firstRowIds
Returns the ROWID (converted to a character string) of the first database query row satisfying the passed query prepare string.
Location: query.p
Parameters:  
INPUT pcQueryString AS CHARACTER
A complete query WHERE clause that matches the database query's buffers.
Returns: CHARACTER
Note: Used by rowidwhere, findRow, and findRowWhere.
initProps
Procedure that, during initialization, sets all the object’s properties that are related to the Query.
Location: query.i
Parameters: None
Notes: None
newQueryValidate
Inserts a new expression to the passed prepare string if the buffer reference, usually extracted from the expression, is valid. Returns the Unknown value (?) if error (after an error message has been shown).
Location: query.p
Parameters:  
INPUT pcQueryString AS CHARACTER
Complete query string to which the expression is going to be added.
INPUT pcExpression AS CHARACTER
The new expression to add to the query. The first field reference is used as buffer reference unless pcBuffer is defined.
INPUT pcBuffer AS CHARACTER
Optional buffer reference.
INPUT pcAndOr AS CHARACTER
Operator used to append if query string already has an expression. Default is "=".
Returns: CHARACTER
Notes:  
The function avoids duplicate logic in add and setQueryWhere and acts as a wrapper for newWhereClause with some significant additions and differences:
*The buffer reference is usually extracted from the new expression.
*pcBuffer is optional and as a result is not the first parameter.
*The buffer reference is validated and qualification does not need to match the original query.
*Displays error message and returns the Unknown value (?) if the buffer is unknown or ambiguous.
newQueryWhere
Returns a new query.
Location: query.p
Parameters:  
INPUT pcWhere AS CHARACTER
Returns: CHARACTER
Note: For internal use only. This functions exists only to have the same logic in setQueryWhere in data.p and query.p. Returns unknown if the buffer reference is invalid.
openQuery
This function opens the database query either for a data object.
Location: query.p
Parameters: None
Returns: LOGICAL
Note: The QueryString property that is modified by the addQueryWhere, assignQuerySelection, and setQuerySort methods is used (if it is not blank) in the QUERY–PREPARE method before opening the query.
prepareQuery
Internal function. Prepares the database query for some querying object such as a SmartDataObject.
Location: query.p
Parameters:  
INPUT pcQuery AS CHARACTER
The complete query expression.
Returns: LOGICAL
Notes:  
The main purpose for this is to prepare a query on an AppServer. You can do this in two different ways:
*The addQueryWhere and assignQueryWhere methods manipulates a client-side property that openQuery checks and uses as input to this method.
*setQueryWhere calls this method and blank properties used by 1 in order to make openQuery NOT call this.
resolveBuffer
This function resolves the correct, qualified buffer name of the passed buffer reference.
Location: query.p
Parameters:  
INPUT pcBuffer AS CHARACTER
Buffer name, qualified or unqualified.
Returns: CHARACTER
Notes:  
*The function returns blank if the buffer cannot be resolved in the SDO. It returns the Unknown value (?) if the table reference is ambiguous, that is, if more than one table in the SDO matches the unqualified input parameter.
*Used internally (columnTable and others) to resolve cases where the qualification of the passed column name is different from that of the object’s name.
*There is no reference to the query handle in order to resolve this on the client.
rowidWhere
Returns the ROWID (converted to a character string) of the first database query row satisfying the where clause. In the case of a join, only the rowid of the first table in the join is returned and the expression in pcWhere can only reference that table.
Location: query.p
Parameters:  
INPUT pcWhere AS CHARACTER
The where clause to apply to the database query to fetch the first record whose ROWID is to be returned.
Returns: CHARACTER
Note: The ROWID is returned as a string both in anticipation of it being used as an argument to fetchRowIdent, and also to allow this function to be invoked from outside the OpenEdge environment.
rowidWhereCols
Returns a list of ROWIDs and adds column/value pairs to the corresponding buffer’s WHERE clause. Each buffer’s expression is embedded in parentheses.
Location: query.p
Parameters:  
INPUT pcColumns AS CHARACTER
Column names (comma-separated). Fieldname of a table in the query in the form of TBL.FLDNM or DB.TBL.FLDNM (only if qualified with db), (RowObject.FLDNM should be used for SDOs). If the fieldname is not qualified, it checks the tables in the TABLES property and assumes the first is a match.
INPUT pcValues AS CHARACTER
Corresponding Values (CHR(1)-separated).
INPUT pcOperators AS CHARACTER
The operator (one for all columns):
*A blank defaults to (EQ).
*A slash is used to define an alternative string operator (EQ/BEGINS, and so forth).
*A comma‑separated list for each column/value.
Returns: CHARACTER
Notes: None
transferDBRow
A procedure that buffer–copies the database records for the current query row into the RowObject temp-table.
Location: query.p
Parameters:  
INPUT pcRowIdent AS CHARACTER
A comma‑separated list consisting of the ROWID of the RowObject record followed by the RowIds of the database records; if unknown or blank, then the database records have already been retrieved.
INPUT piRowNum AS INTEGER
The integer value to assign to the RowNum field in the RowObject temp-table record.
Note: This procedure replaces the transferRowFromDB function from Version 9.0. It can be localized to perform additional custom operations each time a row is transferred from the database to the RowObject table.