Progress
Programming
Handbook


Working with Persistent Procedures

If you do not specify handle when you create a persistent procedure, you can obtain the handle for the procedure using the SESSION system handle. Progress maintains all handles to persistent procedure instances in a chain that you can access. The SESSION handle has two attributes, FIRSTPROCEDURE and LASTPROCEDURE, that provide access to the first and last persistent procedures (respectively) that are created. These attributes return procedure handles that you can use to reference attributes of each persistent procedure context. For a complete list of these attributes, see the THISPROCEDURE System Handle reference entry in the Progress Language Reference .

For example, using the NEXTSIBLING attribute with the FIRSTPROCEDURE handle value or the PREVSIBLING attribute with the LASTPROCEDURE handle value, you can follow the entire chain of persistent procedure handles to locate the one you want. Note that PREVSIBLING of FIRSTPROCEDURE and NEXTSIBLING of LASTPROCEDURE specify invalid handles to terminate the chain. You can check the validity of any procedure handle value in the chain using the VALIDHANDLE function. It returns TRUE for a valid value and FALSE for an invalid value.

The PRIVATEDATA attribute is especially helpful in identifying a particular persistent procedure in the chain. When initially created with the RUN statement, a persistent procedure can set this attribute to a unique character value that helps identify its context to other procedures. You can use shared data to help manage the values for this private data. Note that the FILENAME attribute might not be sufficient to identify a specific persistent procedure instance, because you can create multiple instances of the same persistent procedure.

Other attributes of procedure handles that help manage persistent procedures include the PERSISTENT, CURRENTWINDOW, and INTERNALENTRIES attributes. When used with the THISPROCEDURE handle, the PERSISTENT attribute returns TRUE if the current procedure is being run persistently. This is useful if you want to write a procedure to run either persistently or non-persistently, providing different code options for each mode of execution.

The CURRENTWINDOW attribute allows you to assign a unique current window to a procedure context that never changes as long as the procedure remains in scope or until you reset it. This is especially useful for persistent procedures that maintain their own windows. For more information, see Windows."

The INTERNALENTRIES attribute returns a comma-separated list of all the internal procedures defined within the specified external procedure. This is helpful to identify the functional capabilities (internal procedures) provided to your application by each type of persistent procedure that you create. The GETSIGNATURE method returns the type and parameters of a specified internal procedure.

For example, this code fragment uses several attributes to select persistent procedures that participate in the application user interface, and makes their current windows visible:

DEFINE VARIABLE hcurrent AS HANDLE. 
DEFINE VARIABLE hnext AS HANDLE. 
DEFINE VARIABLE hwindow AS WIDGET-HANDLE. 
hcurrent = SESSION:FIRST-PROCEDURE. 
DO WHILE VALID-HANDLE(hcurrent): 
    IF hcurrent:PRIVATE-DATA = "USER INTERFACE" THEN DO: 
        hwindow = hcurrent:CURRENT-WINDOW. 
        hwindow:VISIBLE = TRUE. 
    END. 
    hcurrent = hcurrent:NEXT-SIBLING. 
END. 

For more information on attribute references, see Widgets and Handles."


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095