skip to main content
OpenEdge Development: ADM Reference
SmartObjects and Their Methods and Properties : Base methods for SmartObjects
 
Base methods for SmartObjects
The following section describes the base methods and general super procedures for the SmartObjects used to create ADM2 applications.
addLink
Procedure that adds a link between two objects by setting property values in each.
Location: smart.p
Parameters:  
INPUT phSource AS HANDLE
Source procedure handle.
INPUT pcLink AS CHARACTER
Link name.
INPUT phTarget AS HANDLE
Target procedure handle.
Notes:  
*A NavigationSource (toolbar) linked to a SmartBusinessObject navigates the SmartDataObject that is linked to the visual DataTarget on a paged container.
*Normally addLink is run from code generated by the AppBuilder in the internal procedure adm–create–objects, in response to the developer adding links to a SmartContainer at design time. Additional calls to addLink can be written into an application when additional links are needed at run time.
*If the link is not in the SupportedLinks list for either object, then the link name is treated as a single subscription in the Target for an event of that name in the Source.
*If the link is in the list of PassThroughLinks, and the object at one end or the other of the new link is a SmartContainer, addLink checks to see if a link of the same type exists for that container. If so, the two links are combined, or chained together, into a single link that connects the original Source with the final Target, bypassing the Container. Refer to documentation for ADM2 or OpenEdge® AppBuilder for more information about PassThrough links.
*If the link name is of the type PageN, where N is an integer, then the caller is defining the Target to be on logical page n of the Source, which must be a SmartContainer. The addLink procedure adds the Target to the special link name PageNTargets in the Source.
*For each entry in an object’s SupportedLinks, there must be a property that stores the handle(s) of the object(s) at the other end of the link, and functions to set and get that property. There must also be a property that stores a list of the named events which are associated with that link. For example, if Navigation–Source is one of a SmartPanel’s SupportedLinks, and Navigation–Target is one of a SmartDataObject’s SupportedLinks, in executing the second example above, addLink adds hdCust to the NavigationTarget property of the SmartPanel, and hSmartPanel to the NavigationSource property of the SmartDataObject. The addLink procedure checks the RETURN data type of the get property functions for these properties: a RETURN type of HANDLE means that only a single object is supported on that end of the link and that the property value is stored as a value of type HANDLE. If the RETURN type is CHARACTER, multiple objects are supported on that end of the link and the object handle is added to a property value stored as a comma‑separated list of object handles. For example, the NavigationTarget property is CHARACTER, because a panel may have multiple Navigation–Targets. The NavigationSource property is HANDLE because an SmartDataObject may have only one Navigation–Source. The NavigationSourceEvents property for the SmartDataObject stores a list of the events to be subscribed to in the Source.
Examples:  
/*  This example defines a dynamic link from MyWindow to the SDOdCust. If the
    link type SpecialEvent is not defined as a SupportedLink for either
    SmartWindows or SmartDataObjects, then addLink will do a single SUBSCRIBE
    in hdCust to ‘SpecialEvent’ in hMyWindow. This means that when code in
    MyWindow does ‘PUBLISH ‘SpecialEvent’." The user-defined internal
    procedure named SpecialEvent in dCust will be executed.*/
 
RUN addLink (INPUT hMyWindow, INPUT ‘SpecialEvent’:U, INPUT hdCust).
 
/*  This example will add an instance of the SupportedLink ‘Navigation’ from
    a SmartPanel to an SDO. Normally this link would be defined at design time
    and the call to addLink generated automatically by the if the SmartPanel
    were run after startup by application code, if response to some
    application event, then the link would need to be created by application
    code also. AddLink will SUBSCRIBE the SDO to fetchFirst, fetchNext,
    fetchPrev, and fetchLast in the SmartPanel, because these events are
    listed in the SmartPanel property NavigationSourceEvents in the SDO. */
 
RUN addLink (INPUT hSmartPanel, INPUT ‘Navigation’:U, INPUT hdCust).
addMessage
Procedure that inserts the message text into a data message log along with its Field, and Table if known.
Location: smart.p
Parameters:  
INPUT pcText AS CHARACTER
Text of the message.
INPUT pcField AS CHARACTER
The field name for which the message occurred, if it was related to a specific field.
INPUT pcTable AS CHARACTER
The database table for which the message occurred, if it was related to an update to a database table.
Notes:  
*If pcText is the Unknown value (?), that signals that this function should retrieve messages from the error–status system handle.
*The message log is a character string in a special format intended to be decoded with the functions fetchMessages or showDataMessages.
*Message texts that are intended to be seen by end users can be enabled for translation into other languages by putting them into the application code as quoted strings, and then using the Translation Manager tool. Generally, ADM messages which are expected to be seen by developers, for example, messages that indicate errors in the application design, are entered into the ADM super procedures as quoted strings with the :U suffix so that they are not seen by the Translation Manager tool.
*If the Unknown value (?) is passed as the message text value, then addMessage retrieves as many error messages as are stored in the ERROR–STATUS handle using the GET–MESSAGE method. This would be appropriate, for example, after executing a database access statement NO–ERROR, then checking the value of ERROR–STATUS:ERROR.
Example:  
 
/* This example adds a specific message to the log for the SDO field whose name
   is stored in the variable cField, for no particular database table. */
 
RUN addMessage ("This operation could not be completed.":U, cField, ?).
adjustTabOrder
Procedure that changes the tab order of SmartObjects.
Location: smart.p
Parameters:  
INPUT phObject AS HANDLE
Handle of the smart object.
INPUT phAnchor AS HANDLE
Handle of either another SmartObject procedure or a widget-handle of the object that anchors the SmartObject.
INPUT pcPosition AS CHARACTER
“After” if the SmartObject is moved after the anchor.
“Before” if the SmartObject is moved before the anchor.
Note: adjustTabOrder calls are generated by the AppBuilder in adm–create–objects. Calls to this procedure can be added to an application to do dynamic re-ordering of the tab order of SmartObjects in a SmartContainer at run time.
Example:  
/* Make sure that the tab order position of a SmartPanel in a SmartWindow is
   immediately before the fill-in field FIELD-1 in that window. */
 
RUN adjustTabOrder (INPUT hSmartPanel, INPUT FIELD-1:HANDLE 
  IN FRAME {&FRAME-NAME}, INPUT "BEFORE":U).
anyMessage
Returns a flag indicating whether there are messages in the error message log.
Location: smart.p
Parameters: None
Returns: LOGICAL
Note: Error messages generated during the execution of SmartObjects (especially SmartDataObjects) are normally saved in a message log (actually just a specially formatted character string). This assures that multiple messages can be accumulated for multiple errors that occur during an update and that messages are returned properly to the client when the errors occur in a separate session on an AppServer. If using a SmartDataObject as the data-source, check BOTH in the SmartDataObject and internally, because WebSpeed-specific errors are always stored internally.
Example:  
IF anyMessage() THEN
/* code for unsuccessful update */
ELSE
/* code for successful update */
applyEntry
Procedure that applies ENTRY to the first enabled and visible object in the default frame (unless pcField is specified) or in the first child that is a Frame.
Location: smart.p
Parameters:  
INPUT pcField AS CHARACTER
An optional field name; if specified (that is, if this parameter is not blank or unknown), the frame field of that name is positioned to.
Notes: None
assignLinkProperty
Sets a property value in one or more SmartObjects at the other end of a specified link, relative to the TARGET–PROCEDURE.
Location: smart.p
Parameters:  
INPUT pcLink AS CHARACTER
Link type.
INPUT pcPropName AS CHARACTER
Property name.
INPUT pcPropValue AS CHARACTER
Property value.
Returns: LOGICAL (TRUE if the property set-function succeeded, else FALSE.)
Notes:  
*This is the Version 9 (ADM2) Version of the set–link–attribute procedure in Version 8. Note that only one property name and value is allowed, as opposed to the attribute-list format of Version 8.
*If the property function is not there or is invalid, or if any of the set-functions fail, this function returns FALSE.
Examples:  
/* This example code from the updateRecord procedure makes sure that when an
   update completes, and the DataModified property is turned off in the
   SmartDataViewer which initiated the update, it is also turned off in all
   other Viewers which may be linked in a GroupAssign. */
 
lSuccess = DYNAMIC-FUNCTION(‘assignLinkProperty’, 
  INPUT ‘GroupAssign-Target’:U, INPUT ‘DataModified’:U, ‘no’:U).
 
/* This example will move focus to the first enabled and visible field in the
   SmartDataViewer vCust. The handle hvCust would normally be available in
  the SmartDataViewer’s container. This statement could follow a message
  indicating that values needed to be entered for the current record, for
  example.*/
 
RUN applyEntry IN hvCust (?).
 
/* This example applied focus to a specific field ("City") in a
   SmartDataViewer. This could result from field validation failing for field,
   for example. See updateRecord in the super procedure datavis.p for an
   actual example of how the ADM repositions focus to a specific field.*/
 
RUN applyEntry In hvCust ("City":U).
changeCursor
Procedure that sets the cursor on all windows and on any dialog box frames that are currently on the screen.
Location: smart.p
Parameters:  
INPUT pcCursor AS CHARACTER
Name of cursor to use. This should be either WAIT or "".
Note: Normally used internally by the ADM. Could be used by application code to set and then clear the WAIT (hourglass) cursor during a lengthy operation.
createControls
Procedure that defines the default action for SmartObject‑specific initialization of ActiveX Controls. Runs adm–create–controls, an AppBuilder-generated procedure.
Location: smart.p
Parameters: None
Note: A localization of this behavior should be placed in a procedure called createControls in the SmartObject. The Version 8-style name adm–create–controls for the standard behavior is maintained in order to allow a localization in the same procedure file.
destroyObject
Procedure that cleans up and deletes the current object procedure and its descendents, if any.
Location: smart.p
Parameters: None
Notes:  
*Checks first to see if any object is not prepared to be destroyed (for example, if DataModified is set). This is done by publishing the named event confirmExit, which is implemented for example in datavis.p for visual data objects which can return FALSE if their DataModified property is set, indicating that they have unsaved changes to the current record. Because of this possible error return, application code that runs destroyObject should check ERROR–STATUS:ERROR to see whether the operation succeeded or not.
*The destroyObject procedure runs removeAllLinks to delete all SmartLinks associated with this object.
*The standard ADM construct for a SmartWindow is to have the CLOSE trigger run destroyObject. Therefore, the statements APPLY CLOSE to hSmartWin and RUN destroyObject IN hSmartWin normally have equivalent results. You should use APPLY CLOSE so as to catch any other effects of this event. For other SmartObjects, RUN destroyObject is the recommended way to destroy the object.
*All SmartContainers PUBLISH destroyObject to delete all the SmartObject procedures they contain, before destroying themselves.
*You can localize the destroyObject procedure to add a check to do cleanup before a destroy completes, or to stop a destroy event from finishing. (See the “confirmExit” section entry for the standard event procedure for doing this.)
displayLinks
Utility procedure used to put up a dialog showing all the ADM links for a given container object.
Location: smart.p
Parameters: None
Notes:  
*Can be executed by selecting displayLinks from the PRO*Tools procedure object viewer for the desired SmartContainer.
*As noted, this is a utility procedure that is not executed by any standard ADM code and is not intended to be called from a SmartObject application.
editInstanceProperties
Procedure that runs the dialog to get run-time property settings.
Location: smart.p
Parameters: None
Notes:  
*Generally run by the AppBuilder in design mode to bring up the dialog procedure that has been defined in the object property include file as the ADM–PROPERTY–DLG preprocessor value. Normally there is one such standard program per template, whose name is specified in the template. This dialog allows application designers to define values for SmartObject properties that are appropriate to assign when an instance of the object is created.
*You can create special InstanceProperty programs for specific types of SmartObjects (a particular SmartDataViewer with extra run-time Properties, for example). No assumptions are made about the structure or functionality of the dialog program except that it sets each of the modified Instance Properties by executing their set property functions. The existing Instance Property dialog procedures in the src/adm2/support directory can be used as models for building new ones or extending existing ones.
*Application code could invoke this procedure (by adding a double-click trigger to a widget, for example), to allow the InstanceProperty dialog to be invoked at run time.
*This is the Version 9 (ADM2) equivalent of the edit–attribute–list procedure in Version 8.
*Generally run by the AppBuilder in design mode.
Examples:  
PROCEDURE editInstanceProperties:
  /* Purpose: Display a different Instance Property Dialog if this object is
              in a Template. Use the normal dialog if this is in a standard
              Master file. */
  DEFINE VARIABLE cInfo AS CHARACTER NO-UNDO.
 
  /* Use the AppBuilder API to determine if this instance is in a Template. */
  RUN adeuib/_uibinfo.p (?, ‘HANDLE ‘:U + STRING(THIS-PROCEDURE),
    ‘TEMPLATE’:U, OUTPUT cInfo).
 
  /* Use a special attribute dialog for templates. */
  IF cInfo = ‘yes’:U THEN
    RUN special.w (INPUT THIS-PROCEDURE).
  /* Dispatch standard ADM event. */
  ELSE
    RUN SUPER.
END PROCEDURE.
exitObject
Procedure that passes an exit request to its container.
Location: smart.p
Parameters: None
Notes:  
*By convention, the standard routine always passes an exit request to its CONTAINER–SOURCE. The container that actually initiates the exit should define a local version and not call the standard one. That local exitObject is built into the SmartWindow template. This allows any SmartObject to initiate a destroy operation on its container. When it runs exitObject (for example, when a user pressing a Done button), this event is passed up through the Container link hierarchy until an object is found that is at the appropriate level to initiate a destroy of all its contents. As noted, this is normally the SmartWindow, where exitObject does APPLY ‘CLOSE’ TO THIS–PROCEDURE, that in turn runs destroyObject.
*exitObject could be customized when you want behavior other than, or in addition to, invoking exitObject in the ContainerSource. As noted, the default localization in SmartWindows is to APPLY CLOSE to initiate a destroyObject sequence. A local version of this, in an object other than a SmartWindow, could do additional custom cleanup. Note that because exitObject is defined in the SmartWindow template, a localization of it in a SmartWindow must exclude the standard code to prevent a duplicate procedure definition.
Example:  
/* This example is taken from the standard code for the “Done” button in the
   AppBuilder palette. If the object containing the button is a SmartWindow,
   then the code executes the standard convention for destroying a
   SmartWindow, APPLY "CLOSE". If not, the code runs exitObject to pass the
   event up to its Container, otherwise the effect would be to destroy only
   the SmartPanel or other SmartObject containing the button, which is
   probably not what is intended. */
&IF "{&PROCEDURE-TYPE}" EQ "SmartWindow" &THEN
  RUN exitObject.
&ELSE
  APPLY "CLOSE":U TO THIS-PROCEDURE.
&ENDIF
fetchMessages
Returns a delimited list of all messages in their raw form. The message log is cleared.
Location: smart.p
Parameters: None
Returns: CHARACTER (specially formatted message string).
Notes:  
*The fetchMessage procedure is not normally expected to be used by application code. The showDataMessages function can be used—and customized if desired—to parse this specially formatted message string into a series of error messages.
*The message list is delimited by CHR(3); within each message, the Message Text, the Field (if any), and the Table (if any) are delimited by CHR(4).
*The fetchMessages function clears the message log, and it is the responsibility of the calling procedure to display the messages or handle them appropriately. Use the similar function reviewMessages to read messages without deleting them.
fixQueryString
Conventionalizes decimal delimiters in query strings to be full-stops.
Location: smart.p
Parameters:  
INPUT pcQueryString AS CHARACTER
The string to be conventionalized.
Returns: CHARACTER
Note: Wherever a query prepare is being used, call this routine immediately to resolve conventional differences in the query string, such as decimal formatting. The main issues arise when the query string contains stringed decimal values.
initializeObject
Procedure that performs general initialization common to all objects.
Location: smart.p
Parameters: None
Notes:  
*There is a version of initializeObject in virtually every Super procedure; each performs the initialization appropriate to that class of objects. This top-level version runs the createControls and control_load procedures, if they exist, to initialize ActiveX Controls in the object, and sets the ObjectInitialized property to TRUE.
*Initialization of SmartObjects takes place in two phases. In the first phase, the constructObject procedure is run (normally from the AppBuilder-generated procedure adm–create–objects) for each SmartObject in a SmartWindow or other container. This runs the persistent procedures which instantiates the object and initializes Instance Properties for which values have been defined. adm–create–objects then creates links between objects. Once this is complete, the container runs initializeObject. This passes the initializeObject event down through all the contained objects. Therefore, any version of initializeObject can assume that all the SmartObjects and SmartLinks in a container have been established and that they can be checked, for example, whether there is a link to some other particular kind of object. Code should not, however, assume the order in which SmartObjects are initialized.
For example, a SmartDataObject opens its query and publishes dataAvailable to signal that to other objects. A SmartDataViewer runs dataAvailable in itself to see if there is already a row waiting for display, which would happen if the associated SmartDataObject was initialized first.
*Application code can therefore localize createObjects in a SmartContainer to add code to the creation phase (for example, to define additional application-specific links or set application-specific properties that need to be looked at during initialization), or to initializeObject to add code to the initialization phase after all objects have been created and all links created. For noncontainer SmartObjects, code to be executed during the creation phase (that is, when the object’s procedure is first run) should be placed in the Main Block. Code to be executed after the object and other related objects have been created should be placed into a local initializeObject.
instanceOf
Takes an object type as input and resolves the query inheritance as defined in the Progress Dynamics Repository.
Location: smart.p
Parameters:  
INPUT pcObjectType AS CHARACTER
The object type for which you want to resolve the inheritance.
Notes:  
*This function is used only in a Progress Dynamics® environment.
*Returns TRUE if the instance inherits from the requested class anywhere in the hierarchy.
instancePropertyList
Returns a list of the values of the names of the object’s InstanceProperties, that is, those properties that can be set to initial values in design mode. These can be set in the AppBuilder to determine the object instance’s behavior at run time.
Location: smart.p
Parameters:  
INPUT pcPropList AS CHARACTER
Optional list of properties wanted. If this parameter is blank, the default is all of the instance properties. Other valid options are "*"(all properties), or a list of the specific properties wanted.
Returns: CHARACTER (Specially delimited list of property names and values.)
Notes:  
*The properties are returned in a string delimited by CHR(3) between property name/value pairs, and CHR(4) between the name and the value.
*Normally used internally by the AppBuilder at application design time to retrieve a list of property names and values to insert into the generated code in the adm–create–objects procedure.
*If the input parameter is the special value ADM–TRANSLATABLE–FORMAT, then the property list string is returned in precisely the form used in generating adm–create–objects, with the special translation suffix :U inserted in the list following nontranslatable property values, and the suffix left off for special translatable properties such as the Tab Folder’s FolderLabels property.
*If the input parameter is the special value *, then all object properties are returned with their values. A list of object properties is determined by identifying all the get property functions for the object (functions beginning get with no following hyphen, taking no input parameters), plus all dynamic properties stored in the UserProperty string.
*If the input parameter is a comma‑separated list of property names, just those properties and their values are returned.
hideObject
Procedure that hides the current object if it is a visual object and sets the ObjectHidden property to TRUE to indicate the state of the object.
Location: smart.p
Parameters: None
Notes:  
*The Hide concept is a logical one; nonvisual objects might also be hidden, meaning that they are not currently active. This might affect whether code in some event procedures is executed. For example, SmartDataObjects does not respond to events such as fetchNext and fetchLast if they are logically hidden, even though they have no visualization. This allows certain SmartLinks to be effectively deactivated when the object at one end or the other is hidden.
*When a SmartContainer is hidden, it is not necessary for all of the objects it contains to be individually hidden because they are hidden along with the container. For this reason, hideObject, when executed for a SmartContainer, sets the property ContainerHidden in each contained SmartObject without actually running hideObject in each object. The setContainerHidden function, in turn, sets the ObjectHidden property to TRUE so that it can be queried successfully. Not running hideObject in each individual SmartObject improves performance when SmartObjects are being paged (alternately hidden and viewed), and can eliminate problems with flashing of visual objects or problems restoring proper frame order when objects are hidden and viewed.
*The hideObject procedure can be localized when behavior in addition to the default is needed when a SmartObject is hidden, for example to decide whether a hidden component should actually be destroyed to conserve memory.
Examples:  
ON CHOOSE OF MENU-ITEM mi_Hide_Children DO:
  DEFINE VARIABLE cHandles AS CHARACTER NO-UNDO.
  DEFINE VARIABLE hSMO     AS HANDLE    NO-UNDO.
  DEFINE VARIABLE ix       AS INTEGER   NO-UNDO.
 
  /* Find all the children of a SmartWindow and HIDE the child windows. */
  cHandles = DYNAMIC-FUNCTION(‘linkHandles’:U, INPUT ‘Container-Target’:U).
 
  DO ix = 1 TO NUM-ENTRIES (cHandles):
    /* cHandles is a comma-separated list of SmartObject handles. */
    hSMO = WIDGET-HANDLE(ENTRY(ix, cHandles)).
    /* See if this SmartObject is a SmartWindow. */
    IF DYNAMIC-FUNCTION(‘getObjectType’:U IN hSMO) = "SmartWindow":U THEN
      RUN hideObject IN hSMO.
  END.
END.
linkHandles
Takes a link name and returns a list of handles of objects at the other end of that link, relative to the TARGET–PROCEDURE.
Location: smart.p
Parameters:  
INPUT pcLink AS CHARACTER
The link name (including -SOURCE or -TARGET).
Returns: CHARACTER (Comma‑separated list of handles to the SmartObject procedures at the other end of the link.)
Notes:  
*This is the Version 9 (ADM2) equivalent of the procedure get–link–handle in Version 8.
*If the link type does not exist in the object, then the empty string ("") is returned.
*The procedure handle list is returned as a character string because (if the link type requested supports multiple objects at that end of the link) there might be multiple SmartObjects connected by that link type, so these come back as a comma‑separated list. The developer must check the NUM–ENTRIES in the returned list (which might be zero, one, or more), and apply the WIDGET–HANDLE function to each entry to derive the procedure’s handle.
Examples:  
/* Here, a pass-through link is created from a SmartDataObject in a parent
   SmartWindow, through the SmartWindow containing this code, to a
   SmartDataBrowser contained in this window. The Data link from the SDO will
   go both to the SmartWindow and to the Browser. There is no standard
   implementation of the ‘dataAvailable’ event that is published whenever a
   new row is selected in the parent SDO, but this local version will intercept
   that event and use it to modify the title of the window. */
 
PROCEDURE dataAvailable:
  /* This input parameter is defined, but we don’t look at it. */
  DEFINE INPUT PARAMETER cType AS CHARACTER NO-UNDO.
 
  DEFINE VARIABLE cValues     AS CHARACTER NO-UNDO.
  DEFINE VARIABLE hDataSource AS HANDLE    NO-UNDO.
  DEFINE VARIABLE hWindow     AS HANDLE    NO-UNDO.
 
  /* Convert the return value directly to a handle because we know there is
     only one Data Source. */
hDataSource = WIDGET-HANDLE(
  DYNAMIC-FUNCTION(‘linkHandles’:U, ‘Data-Source’:U)).
 
  /* Ask for the Customer Name field from a Customer SDO. */
  cValues = DYNAMIC-FUNCTION(‘colValues’:U IN hDataSource, INPUT ‘Name’:U).
 
  /* Get the widget handle of the window itself. */
  hWindow = DYNAMIC-FUNCTION(‘getContainerHandle’:U).
 
  /* First value returned from colValues is always the RowIdent, so skip it. */
  hWindow:TITLE = “Orders for Customer “ + ENTRY(2, cValues, CHR(1)).
END PROCEDURE.
linkProperty
Returns the requested property in the object at the other end of the specified link, relative to TARGET–PROCEDURE.
Location: smart.p
Parameters:  
INPUT pcLink AS CHARACTER
The link name.
INPUT pcPropName AS CHARACTER
The property name.
Returns: CHARACTER: property value in string form.
Notes:  
*This function is the Version 9 (ADM2) equivalent of the request–attribute procedure in Version 8.
*The value is returned in character format, regardless of its native datatype. If there is not exactly one object at the other end of the link, or that object is no longer there, the unknown value is returned.
Examples:  
 
/* This example determines whether the AutoCommit property is TRUE in the
   SmartdataObject associated with the current visual object. */
 
lCommit = DYNAMIC-FUNCTION(‘linkProperty’:U, INPUT ‘Data-Source’:U, 
  INPUT‘AutoCommit’:U).
linkStateHandler
Procedure Handler for the linkState event. This procedure is also used by addLink and removeLink to subscribe and unsubscribe to the link events in the object.
Location: smart.p
Parameters:  
INPUT pcState AS CHARACTER
Mode for the object. The valid values are:
*Add — Activate new link by subscribing to the link events of the passed object.
*Remove — Deactivate removed link by unsubscribing to the link events of the passed object.
*Active — Activate links by subscribing to the link events of the passed object.
*Inactive — Deactivate links by unsubscribing to the link events of the passed object.
INPUT phObject AS HANDLE
Object to which you want to subscribe or unsubscribe.
INPUT pcLink AS CHARACTER
Full link name pointing to the passed object. Both DataSource and Data-source are supported.
Note: The name handler attempts to indicate that this is an event handler that should not be called directly outside of the intended events, but instead be actively used as an event to ensure that properties that are link dependant are set for removal.
mappedEntry
Returns the other entry in a separated list of paired entries. This is required to ensure that the lookup does not find a matching entry in the wrong part of the pair.
Location: smart.p
Parameters:  
INPUT pcEntry AS CHARACTER
Entry to lookup.
INPUT pcList AS CHARACTER
Comma-separated list with paired entries.
INPUT plFirst AS LOGICAL
If TRUE, lookup first and return second. If FALSE, lookup second and return first.
INPUT pcDelimiter AS CHARACTER
Delimiter of pcList.
Returns: CHARACTER
Note: Used to find mapped RowObject or database column in assignList. In other cases, such as the ObjectMapping property of SBOs, an entry might occur more than once in the list, in which case a list of matching values is returned, using the same delimiter as the list.
messageNumber
Returns the message text given a message number. Allows these messages to be translated and tracked in one place.
Location: smart.p
Parameters:  
INPUT piMessage AS INTEGER
Returns: CHARACTER
Notes:  
*In order to allow certain messages to be translated, it is helpful to group them into a single file, since the ADM super procedure source files are not otherwise regarded as part of a translatable application. To facilitate this, messages that are expected to be seen by end users and, therefore, should be translated are located in a single include file (src/adm2/admmsgs.i) in the form of a character array. This allows a translated version of this single file to be substituted and smart.p, which includes admmsgs.i, to be recompiled or run through the Translation Manager tool in order to translate end-user messages that are raised from code located in super procedures.
*The messageNumber function is normally invoked from the addMessage procedure, as in the example.
*The ADM convention is that error messages that are expected to be seen only by developers or application testers (errors indicating errors in application construction, for example, caused by missing links or the like) are not translated, and, therefore, appear in the super procedures as literal strings with the :U suffix.
Example:  
 
/* This example retrieves the text for message number 4 ("Current values must
   be saved or cancelled before Commit.") and passes it to the addMessage
   procedure to add that message to the error message log. */
 
RUN addMessage (messageNumber(4), ?, ?).
modifyListProperty
Procedure that allows values to be added to or deleted from any object property that is a comma‑separated list.
Location: smart.p
Parameters:  
INPUT phCaller AS HANDLE
Handle of the object whose property is being changed.
INPUT pcMode AS CHARACTER
ADD or REMOVE.
INPUT pcListName AS CHARACTER
The name of the property.
INPUT pcListvalue AS CHARACTER
The value to add or remove.
Notes:  
*This is the ADM 2 equivalent of what was modify–list–attribute in the Version 8 ADM.
*Normally the first argument is the handle THIS–PROCEDURE, if the property value is to be changed for the current SmartObject. However, this can be another procedure handle if the property is to be modified in another object.
*The modifyListProperty procedure first runs the getpropname function to retrieve the current value of the property. If a new value is being added, and is already contained in the list, or if a value to be removed is not present in the list, modifyListProperty simply returns without error. Otherwise, the change to the list is made and the setpropname function is run to reset the value of the list property. Both the get and set functions must exist; otherwise, modifyListProperty returns without error.
*There are many ADM Properties that are expressed as comma‑separated lists of handles or other values. All of these should be maintained using the modifyListProperty procedure. Using the setpropname function resets the entire list to the value, which is normally not what is desired.
Examples:  
/* This code will add an additional entry to the SupportedLinks property for
   the object.*/
 
RUN modifyListProperty (INPUT THIS-PROCEDURE, INPUT ‘ADD’:U, 
  INPUT ‘SupportedLinks’:U, INPUT ‘SpecialLink’:U).
 
/* This code adds the specified source procedure handle to the list of
   "Source"s for the specified link in the specifed Target procedure handle
   (from addLink). */
 
RUN modifyListProperty (INPUT phTarget, INPUT ‘ADD’:U, 
  INPUT pcLink + "Source":U, INPUT STRING(phSource)).
modifyUserLinks
Procedure that maintains a delimited list of user-defined links (that is, links that are not in the SupportedLinks list for an object), and the handles of the objects at the other end of the links.
Location: smart.p
Parameters:  
INPUT pcMode AS CHARACTER
ADD or REMOVE.
INPUT pcLinkName AS CHARACTER
The link name including -Source or -Target.
INPUT phObject AS HANDLE
The procedure handle of the object at the other end of the link.
Notes:  
*Run from addLink and removeLink; used primarily by the linkHandles function. When addLink encounters a link that is not in the list of SupportedLinks, it defines a single SUBSCRIBE for an event of that name (see addLink). Because there are no properties where the objects at either end of a nonsupported (or dynamic) link can be stored, they are stored in this list so that functions such as linkHandles, which returns the handle of an object at the other end of a link, can keep track of what the relationships are.
*This function is not intended to be run from application code.
*The list is the third entry in ADM–DATA, delimited by CHR(1). Each entry in the list consists of a link name followed by CHR(4) followed by a comma‑separated list of one or more handles. The list entries are delimited by CHR(3). Users should not be concerned about the specific format and location of the list, which might be subject to change; using this procedure to access the list preserves compatibility with any possible changes.
oneObjectLinks
Procedure that adds linkage for some object.
Location: smart.p
Parameters:  
INPUT hObject AS HANDLE
Handle of the object to be linked.
Note: This procedure is called by displayLinks.
propertyType
Locates the set property function for the specified property name either locally or in a SUPER procedure, and returns its data type.
Location: smart.p
Parameters:  
INPUT pcPropName AS CHARACTER
Property name.
Returns: CHARACTER (The data type of the property.)
Note: This procedure is generally used internally by the ADM.
Example:  
 
/* This code, adapted from the addLink procedure, determines whether a link
   is permitted to have multiple Targets based on whether the supporting
   property function accepts a handle (for a single object handle) or a
   character string (for a comma-separated list of handles. */
 
IF DYNAMIC-FUNCTION(‘propertyType’:U, 
  INPUT pcLinkType + "Source":U) = "CHARACTER":U THEN
  RUN modifyListProperty (‘ADD’:U )   /* Add the string to a list. */
ELSE 
  DYNAMIC-FUNCTION(‘set’:U + pcLinkType + "Source":U, INPUT phTarget).
removeAllLinks
Procedure that removes all links for a SmartObject, normally as part of destroying a SmartObject procedure.
Location: smart.p
Parameters: None
Note: This procedure runs automatically as part of destroyObject. Not normally expected to be run by user application code (see removeLink for a procedure to remove a single specific link).
removeLink
Procedure that removes a specific link between two objects.
Location: smart.p
Parameters:  
INPUT phSource AS HANDLE
Source procedure handle.
INPUT pcLink AS CHARACTER
Link type name.
INPUT phTarget AS HANDLE
Link target object handle.
Notes:  
*This procedure both removes the handles of both Source and Target from the appropriate SmartObject properties (see addLink) and also does an UNSUBSCRIBE for each named event associated with the link.
*All SmartObject links are removed when an object is destroyed. This procedure could be used in application code to remove a specific link based on application requirements.
Example:  
/* This example removed the Update link between a visual SmartObject such as
   a SmartDataViewer and its associated SmartDataObject, perhaps in response
   to an application event or security check which should make the
   SmartDataObject non-updatable. */
hTarget = WIDGET-HANDLE(
  DYNAMIC-FUNCTION(‘linkHandles’, INPUT ‘Update-Target’:U)).
IF VALID-HANDLE(hTarget) THEN
  RUN removeLink(THIS-PROCEDURE, ‘Update’:U, hTarget).
repositionObject
Procedure that adjusts the position of container objects.
Location: smart.p
Parameters:  
INPUT pdRow AS DECIMAL
INPUT pdCol AS DECIMAL
Notes: None
returnFocus
Procedure that returns focus to the containing window.
Location: smart.p
Parameters:  
INPUT hTarget AS HANDLE
A handle to the target procedure object.
Notes: None
reviewMessages
Returns a delimited list of all messages without removing them from the log.
Location: smart.p
Parameters: None
Returns: CHARACTER (Specially delimited message list.)
Notes:  
*reviewMessages is not normally expected to be used by application code. The showDataMessages function can be used (and customized if desired) to parse this specially formatted message string into a series of error messages.
*The message list is delimited by CHR(3); within each message, the Message Text, the Field (if any), and the Table (if any) are delimited by CHR(4).
*reviewMessages is intended to be used in situations where it is necessary to examine messages in the error log without deleting them, so that some other procedure can later process them. Use the similar function fetchMessages to read messages and simultaneously delete them from the log. Note that if all that is needed is to determine if there are any messages in the log, the anyMessage function can be used.
showMessage
Displays, using a simple MESSAGE statement by default, either a literal message string or the return value from a call to messageNumber.
Location: smart.p
Parameters:  
INPUT pcMessage AS CHARACTER
A message string, which might be a message number in string form
Returns: LOGICAL
Note: This function can be overridden to use a mechanism other than the MESSAGE statement to display messages, and still use the messageNumber function to map message numbers to translatable text. Note that this is different from addMessage, fetchMessages, etc., which log messages in a temp-table for later retrieval.
showMessageProcedure
Procedure used by Progress Dynamics override for showMessage function to use Progress Dynamics message handling routines. By default using a simple MESSAGE statement, displays either a literal message string, or a message number that is returned by the messageNumber function. The user’s button choice is returned in the OUTPUT parameter.
Location: smart.p
Parameters:  
INPUT pcMessage AS CHARACTER
Either a literal message string, or a message number in string form. A message number can be followed by a comma-separated list with up to 10 entries. All the entries except the last are used as replacements for parameters of form ‘&n’ in the message string, where n is some number in the range 1 - 9. The last entry must be ‘Question’, ‘YesNo’, or ‘YesNoCancel’, which determines which buttons are provided in the message box.
OUTPUT plAnswer AS LOGICAL
The user’s choice of button: TRUE or FALSE (Question or YesNo), or TRUE/FALSE/UNDEFINED (YesNoCancel).
Notes: None
Example:  
 
showMessageProcedure ("Is this not a nice &1 &2 message?", "short", "sample",
  "Question").
Signature
Returns the signature of the named function or internal procedure in the format returned by the GET–SIGNATURE method.
Location: smart.p
Parameters:  
INPUT pcName AS CHARACTER
The function or procedure name.
Returns: CHARACTER (Signature in GET–SIGNATURE format.)
Notes: None
start-super-proc
Procedure that starts a super procedure if it is not already running and adds it as a super procedure in any case.
Location: smart.i
Parameters:  
INPUT pcProcName AS CHARACTER
Notes: None
viewObject
Procedure that logically views the current object and sets its ObjectHidden property to FALSE.
Location: smart.p
Parameters: None
Notes:  
*The ADM supports a logical concept of viewing that you can apply to all objects regardless of whether they have a visualization.
*When an object is:
*Viewed, the linkState property is typically set to active which activates the links.
*Hidden, the link is sometimes deactivated, depending on the link type. If an object has an actual visualization, the version of viewObject in visual.p views it.
*When a SmartContainer is viewed, it is not necessary for all of the objects it contains to be individually viewed, because they are not explicitly hidden when the container is hidden (see hideObject). For this reason, viewObject, when executed for a SmartContainer, sets the property ContainerHidden to FALSE in each contained SmartObject, without actually running viewObject in each object. The setContainerHidden function then sets the ObjectHidden property to FALSE so that it can be queried successfully. Not running hideObject and viewObject in each individual SmartObject improves performance when SmartObjects are being paged (alternately hidden and viewed), and can eliminate problems with “flashing” of visual objects or problems restoring proper frame order when objects are hidden and viewed.
Example:  
 
/* Views an object when a button is pressed. */
ON CHOOSE OF Btn_View_Browser DO:
  RUN viewObject IN hSDBrowser.
END.