skip to main content
OpenEdge Development: ADM Reference
Data Objects and Their Methods and Properties : Methods for data query objects
 
Methods for data query objects
This section lists and describes methods for data query objects.
addRow
This function creates a new RowObject temp-table record, initializes it, and returns a CHR(1)-separated list of values for the requested columns of the new RowObject row. The first entry in the list is a comma-separated list of the RowObject ROWID and blank values for the database RowIDs that have not been created yet.
Location: data.p
Parameters:  
INPUT pcViewColList AS CHARACTER
A comma‑separated list of column names that are to be displayed in the SmartDataViewer that called addRow.
Returns: CHARACTER
Note: Overrides the DataView class to handle foreign values from a SBO and call newRowObject to set Rowobject fields and call the logic procedure hook.
askQuestion
Procedure that prompts for the maximum number of records to export and confirms the transfer of data in these records.
Location: exportdata.p
Parameters:  
INPUT pcMessage AS CHARACTER
Message to display.
INPUT pcTitle AS CHARACTER
Title of message box.
INPUT plFieldChoice AS LOGICAL
Available options for DisplayFields. You can select:
*Yes — Displays three buttons: Displayed, All, and Cancel.
*No — Displays two buttons: OK and Cancel.
INPUT-OUTPUT piMaxRecords AS INTEGER
Maximum number of records to export.
OUTPUT plDisplayed AS LOGICAL
Idicates which button the user chose in the dialog box. The available ouputs are:
*Yes — All fields.
*No — Displayed fields only
*Unknown value (?) — Cancel
Note: All text is defined as variables in the definition section.
batchRowAvailable
Checks to determine whether there are more records in the batch.
Location: data.p
Parameters:  
pcMode AS CHRAR
Specifies the direction in which to look for records. Values are:
*Next
*Prev
*Current
Note: Use this function before navigating with the normal fetch navigation methods to avoid an implicit read of a new batch in cases when you want to just navigate through one batch of data.
beginTransactionValidate
Wrapper procedure called automatically on entry into a transaction block.
Location: data.p
Parameters: None
Notes: None
cancelRow
This function cancels an Add, Copy, or Save operation.
Location: data.p
Parameters: None
Returns: CHARACTER
Note: Calls to cancelRow in turn call UndoUpdate, which restores the original values of a modified row from the RowObjUpd record then deletes the RowObjUpd record. In the cases of an Add or a Copy, both the new RowObject and the RowObjUpd records are deleted. After all of this work has been done, doUndoUpdate repositions the RowObject temp-table to what was previously the current row.
canNavigate
This function checks if this object or its children have pending updates. Uncommitted changes in children block navigation. This function returns TRUE if it finds nothing to block navigation, while isUpdatePending does the opposite.
Location: data.p
Parameters: None
Returns: LOGICAL
Notes:  
*This routine publishes isUpdatePending because that includes rowObjectState in the check to check the stat of children.
*Navigating objects call this function to check if an object can be navigated. Navigation objects receive updateState from the objects they navigate and must perform this check in the source of any updateComplete message. The updateComplete message can come from a branch of a data-link tree; publishing isUpdatePending checks the whole tree.
clientSendRows
Calls across the AppServer boundary to serverSendRows to fetch a batch of RowObject temp-table records. When the SmartDataObject (SDO) is divided between the client and AppServer, this client-side procedure runs from the generic sendRows procedure and then runs a server-side version that returns the RowObject temp-table records.
Location: data.p
Parameters:  
INPUT piStartRow AS INTEGER
The RowNum value of the record to start the batch to return. Typically piStartRow is the Unknown value (?) as a flag to use pcRowIdent instead of piStartRow.
INPUT pcRowIdent AS CHARACTER
The RowIdent of the first record of the batch to return. Can also be FIRST or LAST to force the retrieval of the first (or last) batch of RowObject records.
INPUT plNext AS LOGICAL
TRUE if serverSendRows is to start on the next record from what is indicated by piStartRow or piRowIdent.
INPUT piRowsToReturn AS INTEGER
The number of rows in a batch.
OUTPUT piRowsReturned AS INTEGER
The actual number of rows returned. This number is either the same as piRowsToReturn or less when there are not enough records to fill up the batch.
Notes:  
*All of the parameters are simply received from the caller and passed through to serverSendRows on the AppServer.
*If piStartRow is not 0 or the Unknown value (?) then pcRowIdent is ignored.
*plNext is ignored if pcRowIdent is FIRST or LAST.
*The most common use of piRowsReturned is to indicate that the entire result list has been returned when it is less than piRowToReturn.
closeQuery
This function closes the RowObject temp-table query (on both the client side and the server side if the SDO is split). It then RUNs SUPER, which invokes closeQuery in query.p, to close the database query.
Location: data.p
Parameters: None
Returns: LOGICAL
Notes: None
colStringValues
Returns a list of values (delimited by the ADM default delimiter set in pcDelimiter) for the requested columns of the current row of the RowObject.
Location: dataextcols.p
Parameters:  
INPUT pcColumnList AS CHARACTER
Comma-separated list of RowObject column names.
INPUT pcFormatOption
Format of returned values. Possible values are:
*Blank or Unknown value (?) — No formatting, buffer values only.
*Formatted — Formatted according to the columnFormat with right justified. numeric values.
*Trim Numeric — Formatted according to the columnFormat with Left justified numeric values.
INPUT pcDelimiter
Optional delimiter (default CHR(1)).
Returns: CHARACTER
Note: This function is different from colValues in that it does NOT return rowidents as the first entry and does not look in the dataSource.
colValues
Returns a CHR(1)‑separated list of values for the requested columns (in pcViewColList) of the current row of the RowObject. The first value is the RowObject ROWID and RowIdent (the RowIDs of the database records from which the RowObject row is derived)-separated with a comma. Subsequent values are formatted according to each column’s FORMAT expression.
Location: dataextcols.p.
Parameters:  
INPUT pcViewColList AS CHARACTER
A comma‑separated list of RowObject column names.
Returns: CHARACTER
Note: The form of the first value is: <RowObject ROWID>,<DB Buffer1 ROWID>,<DB Buffer2 ROWID>. This is used as a key to uniquely identify the row and its origins in the database.
Commit
Client-side part of the Commit function. Copies changed records into an update temp-table and sends it to the serverCommit procedure.
Location: data.p
Parameters: None
Returns: LOGICAL
Notes:  
*Called by commitTransaction, which is called by submitRow. The submitRow code has already reserved an unchanged copy of each record to be updated, in case the update must be undone.
*Invokes procedures in the SmartDataObject itself to manipulate the RowObject temp-tables.
commitData
Procedure that calls undoTransaction to clean up the temp-tables after the commit operation finishes.
Location: dataextapi.p
Parameters:  
OUTPUT pcError AS CHAR
Notes: None
commitTransaction
This event procedure receives the Commit message from a Commit panel or other Commit source. It then invokes the Commit function to actually commit the changes. After the Commit function finishes, commitTransaction handles any error messages by calling showDataMessages.
Location: data.p
Parameters: None
Note: A transaction block is opened in serverCommit (called by the commit function) only if the SDO is split between the client and server. That is, no transaction block occurs on the client side of a split SmartDataObject.
copyRow
This function creates a new RowObject temp-table record, copies all of the current row values to it. The return value of this function is a CHR(1)‑separated list of the values of the current row as specified in the input parameter pcViewColList. The first value of this return value is the RowIdent of the newly created row.
Location: data.p
Parameters:  
INPUT pcViewColList AS CHARACTER
A comma‑separated list of columns whose values are to be returned for the newly created row.
Returns: CHARACTER
Note: This is an override of the DataView mostly because of copyColumns and newRowobject. newRowobject is only in the Data class and overriding this here free the DataView to have a cleaner implemention.
createData
Creates a new record for a data object.
Location: dataextapi.p
Parameters:  
pcColumnNames AS CHARACTER
Comma-separated list of column names.
pcNewValues AS CHARACTER
Current values of the updated record-separated by the Data Delimiter property. For more informationm, see the “DataDelimiter” section.
pcError AS CHARACTER
All error messages in ADM/Dynamic format.
Note: Output data is formatted according to the DataReadFormat property.
createObjects
This procedure defines the temp-tables for a dynamic SmartDataObjects.
Location: data.p
Parameters: None
Note: This functionality is in createObjects because this is the common API used to realize objects for design time use.
createRow
Accepts a list of values to create a new row in a RowObject temp-table.
Location: data.p
Parameters:  
INPUT pcValueList AS CHARACTER
CHR(1)-separated list of alternating column names and values to be assigned.
Returns: LOGICAL
Notes:  
*If an error occurs, it returns FALSE.
*Committing the changes back to the database is a separate step, which is invoked from here if AutoCommit is set on.
dataAvailable
This event procedure handles changes to data on a dataSource, changes to a record position, or a change to the data or record position of this object. Changes are handled by assigning a new value to the ForeignFields property, reopening the query, resetting QueryPosition, and republishing the event.
Location: data.p
Parameters:  
INPUT pcRelative AS CHARACTER
Provides information about a new or changed record. Valid entries are:
*SAME — Performs a RETURN only because the new record is the same as the current record.
*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.
*VALUE–CHANGED — Indicates that the data target has changed position. However, ensures that the query is not reopened but published as DIFFERENT from from this point so the data targets for this object are opened.
*DIFFERENT — Reapply Foreign Fields values except when called from a dataTarget. It that instance, handle as VALUE-CHANGED.
*FIRST, NEXT, PREV, LAST, REPOSITIONED — Handle 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: The dataTarget passes VALUE-CHANGED to indicate a change that does not require the value for foreign fields be reapplied. As a result, the source for dataAvailable does not need to be checked, and this procedure provides support for SmartBusinessObjects (SBOs) as dataSources.
dataContainerHandle
An AppServer-aware container that handles data requests and also acts as the container of THIS object. The container can be a standard container or an SBO.
This function also provides the required checks of the AppServer properties for THIS object and returns only the handle if the current or permanent state allows it to be part of a stateless request handled by another object.
Location: data.p
Returns: HANDLE
Notes: None
deleteData
Deletes an existing record of a data object.
Location: dataextapi.p
Parameters:  
pcColumnNames AS CHARACTER
Comma-separated list of column names.
pcOldValues AS CHARACTER
Current values of the updated record delimited by the DataDelimiter property. For more information, see the “DataDelimiter” section. The values are used to support optimistic locking and also to identify the record.
pcError AS CHARACTER
All error messages in ADM/Dynamic format.
Notes:  
*For information about the columns that identify the record, see the “KeyFields” section
*Rowid and RowIdent are supported as a value in the ColumnNames parameter.
deleteRow
Submits a row for deletion. Returns FALSE if an error occurs.
Location: data.p
Parameters:  
INPUT pcRowIdent AS CHARACTER
The RowId of the RowObject temp-table to delete. The Unknown value (?) means delete the current row.
Returns: LOGICAL
Note: If auto-commit is on, the row is immediately returned to the database for deletion.
describeSchema
A procedure that returns a temp-table with a schema description in it, assembled by this routine.
Location: data.p
Parameters:  
INPUT pcIndexFieldList AS CHARACTER
The list of fields of interest.
OUTPUT TABLE-HANDLE hTtSchema
The handle to the ttSchema table.
Notes: None
destroyObject
This procedure overrides destroyObject to get rid of the datalogic object.
Location: data.p
Parameters: None
Notes: None
doBuildUpd
A procedure that transfers changed rows into the Update temp-table and returns it to the Commit function (the caller function).
Location: dataext.p
Parameters: None
Notes:  
*This code must be inside the SmartDataObject itself to allow the BUFFER-COPY operations. They can be specialized by defining like-named procedures in another support procedure.
*For each existing row to be updated, there is already a before copy in the RowObjUpd table, so create an after row.
*There is already a row in RowObjUpd for each Added/Copied row, so just update it with the latest values.
*There is already a row in RowObjUpd for each Deleted row, so there is no need to do anything for these rows.
doCreateUpdate
A procedure that uses FIND to find the specified row to be updated and saves a copy into the RowObjUpd table, to support Undo. Run from submitRow when it receives a set of value changes from a UI object.
Location: dataext.p
Parameters:  
INPUT pcRowIdent AS CHARACTER
Encoded key of the row to be updated.
INPUT pcValueList AS CHARACTER
Chr(1)-separated list of FieldName/NewValue pairs.
OUTPUT plReopen AS LOGICAL
TRUE if the row is new, the result of a COPY or ADD.
OUTPUT pcMessage AS CHARACTER
Error message, if any.
Note: Run from submitRow. Returns error message or "". If the row is not available in the RowObject temp-table (this would be because the SmartDataObject was not the DataSource) this routine FINDs the database record(s) using the RowIdent key before applying the changes, unless it’s a new row.
doEmptyTempTable
A procedure that empties the RowObject temp-table when the query is reopened while a transaction is active.
Location: dataext.p
Parameters: None
Note: This routine is only needed when a transaction is active. In other cases, use the faster EMPTY-TEMP-TABLE method.
doReturnUpd
A procedure that runs from Commit on the client side. Obtains the latest state of the records in RowObjUpd from the server for refreshing data-display objects.
Location: dataext.p
Parameters:  
INPUT cUndoIds AS CHARACTER
List of any RowObject ROWIDs for which changes were rejected by a commit. Takes the form of RowNum/ADM-ERROR-STRING pairs, CHR(3) separators inside the pairs, comma separators between the pairs.
Notes:  
*If the error string in cUndoIds is ADM-FIELDS-CHANGED, then another user has changed at least one field value. In this case, RowObjUpd fields contains the refreshed db values and passes those values back to the client.
*If not autocommit, also reposition here. Otherwise, the caller has both the rowident and more information, (submitCommit knows whether a reopen is required; deleteRow just uses fetchNext if required).
doUndoDelete
A procedure that restores deleted rows.
Location: dataext.p
Parameters: None
Note: This is separated because:
*A failed commit should restore this, otherwise the user has to undo to correct mistakes.
*The regular undo needs to restore these.
doUndoRow
A procedure that restores the row using the saved image of the unchanged RowObjUpd record.
Location: dataext.p
Parameters: None
Notes: None
doUndoTrans
Procedure that performs the buffer delete and copy operations needed to restore the RowObject temp-table when an Undo occurs. Added or copied records are deleted, modified and deleted records are restored. The RowObjUpd table is emptied.
Location: dataext.p
Parameters:  
INPUT cUndoIds
List of any RowObject ROWIDs for which changes were rejected by a commit. Takes the form of RowNum/ADM-ERROR-STRING pairs, CHR(3) separators inside the pairs, comma separators between the pairs.
Note: Called by the event procedure undoTransaction. Runs on the client side.
doUndoUpdate
Procedure that supports cancelRow by copying the current RowObjUpd record back to the current RowObject record.
Location: dataext.p
Parameters: None
Notes: None
endTransactionValidate
An optional validation procedure called automatically by serverCommit after completing all updates, but before exiting the transaction block.
Location: data.p
Parameters: None
Notes: None
fetchBatch
This procedure transfers another batch of rows from the database query to the RowObject temp-table query, without changing the current record position.
Location: data.p
Parameters:  
INPUT plForwards AS LOGICAL
The direction from which to retrieve the next batch of records. If TRUE, it retrieves the block of rows following the current row. If FALSE, it retrieves the block preceding the current row.
Notes:  
*This procedure runs from a Browser to get another batch of rows from the database query appended to the RowObject temp-table query (when the browser scrolls to the end and not all rows have been retrieved).
*fetchBatch does some checking and sets up the proper parameters to sendRows, but sendRows is called to do the actual work.
fetchFirst
This procedure repositions the RowObject temp-table to the first record or to the row matching the QueryRowIdent property (if it has been set.) If the first record has not been fetched yet, then it calls sendRows to get the first batch of RowObject records of the data object and then repositions the RowObject Temp-Table to the first row.
Location: data.p
Parameters: None
Notes: None
fetchLast
This procedure repositions the RowObject query to the last row of the data set. If the last row has not yet been retrieved from the database, then fetchLast gets the last batch of RowObject records for the SDO and repositions the RowObject query to the last row.
Location: data.p
Parameters: None
Notes:  
*If the SDO RebuildOnReposition property is FALSE and the last row from the database query has not yet been fetched, fetchLast keeps asking for batches of rows until the last batch is received. This is required, otherwise there would be a discontinuous set of rows in the RowObject temp-table.
*If RebuildOnReposition is TRUE and the last row from the database query has not yet been fetched, all RowObject records are discarded and just the last batch is fetched. In this case, the RowNum of the last row becomes 2000000 (just to start with a high value so that all RowNum values continues to be positive integers), and all other records have smaller numbers (except for additions).
fetchNext
This procedure repositions the RowObject query to the next row. If a new batch is required to do so, then sendRows is called to get the new batch.
Location: data.p
Parameters: None
Notes: None
fetchPrev
This procedure repositions the RowObject query to the previous row. If a new batch is needed to do so, then it calls sendRows to get the new batch. Getting a new batch is only necessary when the RebuildOnReposition property is TRUE.
Location: data.p
Parameters: None
Notes: None
fetchRow
Repositions the Row Object’s query to the desired row (indicated by piRow) and returns that row’s values (as specified in pcViewColList). The return value is a CHR(1)‑separated list of values (formatted according to each columns FORMAT expression). The first value in the list is the RowIdent of the fetched row.
Location: data.p
Parameters:  
INPUT piRow AS INTEGER
The desired row number within the result set.
INPUT pcViewColList AS CHARACTER
A comma‑separated list of names of columns to be returned.
Returns: CHARACTER
Notes: None
fetchRowIdent
Repositions the RowObject’s query to the desired row, based on the corresponding database record ROWID as specified by pcRowIdent and returns values for the rows as specified in pcViewColList. The return value is a CHR(1)‑separated list of values that are formatted according to the FORMAT expression for each column. The first value in the list is the RowIdent of the fetched row. If that row is not in the RowObject table, it repositions the database query to that row and resets the RowObject table.
Location: data.p
Parameters:  
INPUT pcRowIdent AS CHARACTER
The desired rowids within the result set, expressed as a comma‑separated list of database rowids.
INPUT pcViewColList AS CHARACTER
Comma-separated list of names of columns to be returned.
Returns: CHARACTER
Notes:  
*If called with unknown or nonexisting rowid, the query is closed and the SDO fetchNext and Prev do not work. The application needs to call fetchRowident with a valid value or fetchFirst, fetchLast, or openQuery to get back to normal.
*This method resolves the row reposition on the server. As a result, the SDO can no longer determine whether the row position is invalid until after the request has been executed. However, if the RebuildOnRepos property is set to TRUE, the temp-table is emptied before the request.
*The current behavior for a FIND that does not find anything when RebuildOnRepos is TRUE is to read the current batch again.
findRowWhere
This function finds a row and repositions to that row.
Location: data.p
Parameters:  
INPUT pcColumns AS CHARACTER
For a SmartBusinessObject (SBO), 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).
For a SmartDataObject (SDO), column names (comma-separated); fieldname of a table in the query in the form of RowObject.FLDNM.
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
A CHR(1)-separated list of the corresponding values for the columns.
INPUT pcOperators AS CHARACTER
A comma-separated list of operators, one for each column/value pair.
Returns: LOGICAL
Notes:  
*This method resolves the row reposition on the server. As a result, the SDO can no longer determine whether the row position is invalid until after the request has been executed. However, if the RebuildOnRepos property is set to TRUE, the temp-table is emptied before the request.
*The current behavior for a FIND that does not find anything when RebuildOnRepos is TRUE is to read the current batch again.
*The logic is in the query.p super.
firstRowIds
Returns the ROWID (converted to a character string) of the first database query row satisfying the passed query prepare string.
Location: data.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.
hasActiveAudit
This function returns the value of hasActiveAudit.
Location: data.p
Parameters: None
Returns: LOGICAL
Notes: None
hasActiveComments
This function returns the value of hasActiveComments.
Location: data.p
Parameters: None
Returns: LOGICAL
Notes: None
hasForeignKeyChanged
This function determines whether or not the dataSource foreign fields are different from the current ForeignValues.
Location: data.p
Parameters: None
Returns: LOGICAL
Notes:  
*The function returns TRUE if the dataSource foreign fields are different from the current ForeignValues. If TRUE, the query needs to be reopened.
*This function is an important part of the logic used with the dataAvailable when RESET is specified.
*Uncommitted values are not considered to be a change, so the dataSource's before-image values are checked if RowObjectState is RowUpdated.
*The ForiegnKey is considered changed if the query closes.
*Used by SmartBusinessObject (SBO) commitTransaction.
hasOneToOneTarget
Returns TRUE if this DataObject has DataTargets that are updated as part of this.
Location: data.p
Parameters: None
Returns: LOGICAL
Notes: None
initializeObject
This procedure performs SDO-specific initialization. Specifically, it starts the server-side copy of this object if the AppService (partition) is defined.
Location: data.p
Parameters: None
Notes: None
initializeLogicObject
Procedure that loads the data logic procedure as a super procedure.
Location: data.p
Parameters: None
Notes: None
isUpdatePending
This procedure publishes to data-targets to check pending updates. It returns TRUE and stops publishing if there is a pending update.
This version overrides DataView to include UpdateFromSource and RowObjectState.
Location: data.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.
newRowObject
Assigns some general RowObject fields and updates LastRowNum and FirstRowNum when a new RowObject has been created.
Location: data.p
Parameters:  
INPUT pcMode AS CHARACTER
The operation to be performed. Valid values are Add and Copy.
Returns: LOGICAL
Notes:  
*The main purpose for this procedure is to ensure that copy and add behaves similarly.
*The buffer must be created first.
*Currently defined as PRIVATE.
*Used in procedure copyColumns and function addRow().
obtainContextForServer
Function that returns a list of properties and sets the required client query context properties.
Location: data.p
Returns: CHARACTER
Parameters: None
Note: Called from initializeServerObject or directly when the single-hit stateless procedures are called.
openDataQuery
This function opens the SDO’s database query based on the current WHERE clause.
Location: data.p
Parameters:  
INPUT pcPosition AS CHARACTER
Where to reposition after opening the query. The valid values are:
*First — Open on the first record.
*Last — Open on the last record.
*WHERE <criteria> — Open on the record matching the WHERE clause.
*STRING(Rowid) — Open on the record with this Rowid.
*""(Blank) — Open the query but do not position.
Returns: LOGICAL
Note: This function is currently used by SBOs after new temp-tables have been fetched.
openQuery
This function opens the data object’s database query based on the current WHERE clause.
Location: data.p
Parameters: None
Returns: LOGICAL
Notes: None
postTransactionValidate
Optional validation procedure called automatically by serverCommit after all updates complete and the transaction block ends.
Location: data.p
Parameters: None
Notes: None
prepareErrorsForReturn
Procedure that appends the RETURN-VALUE to the list of logged errors, formats the string for return to the client. Called from serverCommit.
Location: data.p
Parameters:  
INPUT pcReturnValue AS CHARACTER
INPUT pcASDivision AS CHARACTER
INPUT-OUTPUT pcMessages AS CHARACTER
Note: PRIVATE procedure.
preTransactionValidate
Optional validation procedure called automatically by serverCommit and before entering the transaction block.
Location: data.p
Parameters: None
Note: Use this in place of TransactionValidate (maintained for backward compatibility).
pushTableAndValidate
When running from a SmartBusinessObject, acts as a wrapper for preTransactionValidate and postTransactionValidate procedures.
Location: data.p
Parameters:  
INPUT pcValType AS CHARACTER
Type of procedure needing the wrapper. Valid values are Pre and Post.
INPUT-OUTPUT TABLE FOR RowObjUpd
Returns: RETURN-VALUE
Notes: None
refreshRow
This procedure retrieves the current database values for a row already in the RowObject table.
Location: data.p
Parameters: None
Note: Publishes dataAvailable('SAME') to cause a SmartDataViewer or Browser to display the latest values. Since reading does not lock the database records, you can use this procedure to fetch the latest values upon a request from an application. However, this cannot guarantee that the values do not change before an update.
remoteCommit
Procedure executed on a server side SmartDataObject. This is the equivalent of serverCommit, but can be run in a non- initialized object as it has INPUT and OUTPUT parameters for context.
Location: data.p
Parameters:  
INPUT-OUTPUT pcContext
INPUT context is current context from the client and OUTPUT context is the new context.
INPUT-OUTPUT TABLE RowObjUpd
The Update version of the RowObject temp-table.
OUTPUT cMessages
A CHR(3)-separated string of accumulated messages from the server.
OUTPUT cUndoIds
List of RowObject ROWIDs whose changes must be undone because of errors. The list uses the following form to display theRowObject ROWIDs whose changes need to be undone: RowNumCHR(3)ADM-ERROR-STRING,RowNumCHR(3)ADM-ERROR.
Note: If another user modifies the database records after the original records are read, the new database values are copied into the RowObjUpd record and returned to Commit so the user interface object can display them.
remoteSendRows
A stateless version of sendRows that does no processing but runs sendRows to pass all parameters except for the context and returns the RowObject table as an output parameter to the caller that has the new batch of records created in sendRows.
Location: data.p
Parameters:  
INPUT-OUTPUT pcContext
CHR(3)-separated list of propCHR(4)value pairs. INPUT is the current context and OUPTPUT is the new context. The INPUT and OUTPUT can have different properties.
INPUT piStartRow
The RowNum value of the record to start the batch to return. Typically piStartRow is a flag with a value of the Unknown value (?) that indicates pcRowIdent should be used instead of piStartRow.
INPUT pcRowIdent
The RowIdent of the first record of the batch to return. Can also be FIRST or LAST to force the retrieval of the first or last batch of RowObject records.
INPUT plNext
Determines whether serverSendRows should start on the next record instead of what is indicated by piStartRow or piRowIdent. If TRUE, serverSendRows should start on the next record instead of what is indicated by piStartRow or piRowIdent.
INPUT piRowsToReturn
The number of rows in a batch.
OUTPUT piRowsReturned
The actual number of rows returned. This number is either the same as piRowsToReturn or less if there are not enough records to fill the batch.
OUTPUT pcMessages
Used for error messages.
Notes:  
*If piStartRow is not 0 or the Unknown value (?), then pcRowIdent is ignored. plNext is ignored if pcRowIdent is FIRST or LAST. The most common use of piRowsReturned is to indicate that the entire result list has been returned when it is less than piRowToReturn.
*The object should only be started persistently before this is called and not initialized because initializeObject is run after the context has been set.
*The caller is responsible for destroying the object.
*For more details, see synchronizeProperties and genContext.
saveContextAndDestroy
Procedure that saves the context of the server-side SmartDataObject in support of running in Stateless mode and then destroys it.
Location: data.p
Parameters:  
OUTPUT pcContext AS CHARACTER
The context string to be returned.
Note: saveContextAndDestroy is invoked from the client side of the SmartDataObject and executed on the server side.
sendRows
Procedure that fetches the requested number of rows from the database Query and creates corresponding records in the Row Object temp-table. The batch typically starts at the row indicated by the pcRowIdent parameter, however, it can start on the row indicated by the piStartRow parameter.
Location: data.p
Parameters:  
INPUT piStartRow AS INTEGER
The RowNum to start on. The Unknown value (?) indicates that the next argument (pcRowIdent) determines the start of the batch to be returned.
INPUT pcRowIdent AS CHARACTER
An alternative to StartRow. It is either FIRST, LAST, or a comma‑separated list of database ROWIDs. If it is FIRST or LAST, the first or last batch of records in the result set is retrieved and piStartRow is forced to the Unknown value (?). If it is a comma‑separated list of database ROWIDs, the batch starts with a RowObject that comprises those records.
INPUT plNext AS LOGICAL
TRUE if the query should perform NEXT/PREV (depending on the direction of navigation) before starting to return more rows. In other words, SKIP to the next record at the start of the batch.
INPUT piRowsToReturn AS INTEGER
The maximum number of rows to return (supply a negative value to move backwards in the result set).
OUTPUT piRowsReturned AS INTEGER
The actual number of rows returned.
Note: Before returning, sendRows repositions the RowObject query to what was the current row when it started. The pcRowIdent argument is used by fetchRowIdent to allow query repositioning to a specific database query row.
serverCommit
Server-side counterpart of the client-side Commit function, used when running in n-tier (client + AppServer) mode. This procedure receives from the client-side counterpart a dual set of records (original and changed versions) for update. If comparing the original and current versions reveals no outside changes, updates the records. Otherwise, returns the current (changed) versions to the client side without update, for display to the user.
Location: data.p
Parameters:  
INPUT-OUTPUT TABLE FOR RowObjUpd
The Update version of the RowObject temp-table.
OUTPUT cMessages AS CHARACTER
A CHR(3)-separated string of accumulated messages from the server.
OUTPUT cUndoIds
List of any RowObject ROWIDs for which changes were rejected by a commit. Takes the form of RowNum/ADM-ERROR-STRING pairs, CHR(3) separators within pairs, comma separators between pairs.
Note: The current versions of not-updatable records, if any, are returned in the RowObject temp-table.
serverSendRows
Server-side procedure called by its counterpart (clientSendRows) when operating in n-tier mode (client, AppServer). This procedure acts as a pass-through proxy to sendRows for assembling and retrieving a batch of records. Runs in the ASHandle if in a SmartBusinessObject.
Location: data.p
Parameters:  
INPUT piStartRow AS INTEGER
The RowNum value of the record to start the batch to return. Typically piStartRow is the Unknown value (?) as a flag to use pcRowIdent instead of piStartRow.
INPUT pcRowIdent AS CHARACTER
The RowIdent of the first record of the batch to return. Can also be FIRST or LAST to force the retrieval of the first (or last) batch of RowObject records.
INPUT plNext AS LOGICAL
TRUE if serverSendRows is to start on the NEXT record offset from piStartRow/piRowIdent. Ignored if pcRowIdent is FIRST or LAST.
INPUT piRowsToReturn AS INTEGER
The desired number of rows to return.
OUTPUT piRowsReturned AS INTEGER
The actual number of rows returned. This number is always <= piRowsToReturn.
Notes:  
*All of the parameters are simply received from the client and passed through to sendRows. The temp-table result is then received from sendRows and passed back to the client counterpart routine.
*If piStartRow is not 0 or the Unknown value (?) then pcRowIdent is ignored. plNext is ignored if pcRowIdent is FIRST or LAST.
*The most common use of piRowsReturned is to indicate that the entire result list has been returned when it is less than piRowToReturn.
startServerObject
When a SmartDataObject is split and running statelessly on an AppServer, this procedure runs on the client to start the SmartDataObject on the server.
Location: data.p
Parameters: None
Note: This override is for error handling to show error message and returns adm–error.
submitCommit
Called by submitRow, this procedure commits changes to the database.
Location: data.p
Parameters:  
INPUT pcRowIdent
The identifier of the row to commit. It is a comma‑separated list of ROWIDS. The first entry is the ROWID of the RowObject temp-table containing the record to commit. Subsequent entries in the comma‑separated list are the database ROWIDs of the records to be modified.
INPUT plReopen
TRUE if the RowObject query is to be reopened and repositioned to the RowObject record identified by pcRowIdent.
Notes: None
submitForeignKey
Called from submitRow, this procedure defines Foreign Key values for a new row.
Location: data.p
Parameters:  
INPUT pcRowIdent
The RowIdent (a comma‑separated list of ROWIDs that uniquely identify the RowObject record) of the new RowObject record to be stored in the database. Since this is a new record, only the first ROWID (that of the RowObject itself) is valid. There are no database ROWIDs because they have not yet been created.
INPUT-OUTPUT pcValueList
A CHR(1)‑separated list of column and value pairs to be set in the RowObject record identified by pcRowIdent. On input it is a list that has been set before submitForeignKey was called. On output it is the now current list with the addition of any foreign fields that have been set.
INPUT-OUTPUT pcUpdColumns
A comma‑separated list of column names that are updatable in the SmartDataObject. If ForeignFields are set and added to the pcValueList, they are also added to pcUpdColumns to let the calling code know that it is permissible to update them.
Notes:  
*The list of updatable fields (pcUpdColumns—derived from the UpdatableColumns property in submitRow) usually does not contain key fields. However, because submitForeignKey is called when creating a new RowObject record, key fields need to be populated, so pcUpdColumns is expanded to allow for this. However, only the variable pcUpdColumns is expanded. The UpdatableColumns property remains unchanged.
*You can use this procedure to automatically assign foreign key values t when new records are created. For example, if the current SmartDataObject is for Orders of the current Customer, where the Customer is maintained in a parent SmartDataObject query, then when new orders are added, the CustNum value for the current Customer should be assigned automatically to all newly created Orders. This procedure does that by adding the CustNum field and its value to the list of modified fields. In addition, since these ForeignFields are often not directly updatable (would not be enabled in a visualization), the code also needs to let the calling code (the submitRow function) know that the Foreign Field update should be allowed. It is for this reason that the UpdColumns parameter is passed; the key fields being updated are added to the parameter value if they are not already there. As noted, this also modifies the list of updatable columns only for this one transaction; it does not cause the caller to modify the UpdatableColumns property itself.
*The submitForeignField procedure can be localized in a particular application’s SmartDataObject to make other changes to the initial values of newly created records by modifying the two INPUT–OUTPUT parameters as described here; what is done in the standard code for ForeignFields can be done by application code for other fields to be initialized.
submitRow
This function accepts a list of changed values for a row and ASSIGNs them, returning FALSE if any errors occur. This is done only to the RowObject temp-table. Committing the changes back to the database is a separate step, which is invoked from here if AutoCommit is set to on.
Location: data.p
Parameters:  
INPUT pcRowIdent AS CHARACTER
The RowObject ROWID, which is typically derived from the DataTarget’s Rowident property. The Unknown value (?) indicates the current record.
INPUT pcValueList AS CHARACTER
A CHR(1)‑separated list of alternating column names and values to be assigned.
Returns: LOGICAL
Notes: None
undoClientUpdate
This procedure rolls back updates to the RowObject table in the event of a client-side error. Using a FOR EACH loop, BUFFER-COPYs appropriate RowObjUpd records to RowObject, omitting RowMod.
Location: data.p
Parameters: None
Note: This is to deal with errors before commit has been run - i.e. client side validation errors.
updateAddQueryWhere
Procedure restores a query to design-time state, re-adds the filters, then adds and saves the new WHERE clause.
Location: data.p
Parameters:  
INPUT pcWhere AS CHARACTER
New WHERE clause.
INPUT pcField AS CHARACTER
Field to search and replace.
Notes:  
*Ensures WHERE clause added is not cleared by filters, and is not duplicated in saved manualaddquerywhere. Where clause must be in correct format for an addquerywhere. If WHERE clause is blank but the field is passed in, then manual queries for that field are removed and default back to all.
*Only supports adding a single where clause, but may be called many times. Used when putting a manual filter viewer above a browser.
updateData
Updates an existing record.
Location: dataextapi.p
Parameters:  
pcUpdateColumnNames AS CHARACTER
Comma-separated list of column names.
pcOldValues AS CHARACTER
Current values of the updated record delimited by the DataDelimiter property. For more information, see the “DataDelimiter” section. The values are used to support optimistic locking and also to identify the record.
pcNewValues AS CHARACTER
Current values of the updated record delimited by the DataDelimiter property. For more information, see the “DataDelimiter” section.
pcError AS CHARACTER
All error messages in ADM/Dynamic format.
Note: Output data is formatted according to the DataReadFormat property.
updateQueryPosition
This procedure overrides and duplicates some of the logic in DataQuery to account for the use of RowNum and the possibility of being inside an SBO.
Location: data.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 database query.
updateRow
Updates an existing row.
Location: data.p
Parameters:  
INPUT pcKeyValues AS CHARACTER
A comma-separated or CHR(1)-separated list of keyvalues.
INPUT pcValueList AS CHARACTER
A CHR(1)-separated list of alternating column names and values to be assigned.
Returns: LOGICAL
Notes: None