Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

> ## Using the General Manager

> As its name implies, the General Manager has API calls to support a number of different kinds of general-purpose requirements. These are summarized in the overview section at the top of this chapter.

> Use the `getEntityDescription` procedure to retrieve a field value from any record of any table, given its key. This is a valuable way to get needed values from the Repository database without embedding hard-coded references to the Repository table structures into your code. It also handles the client/server division for you transparently. See OpenEdge Development: Progress Dynamics Managers API Reference for details on every call available in the General Manager.

> There are other useful API calls provided by the General Manager. The first is `getRecordDetail`. Use this call to pass any query to the manager and get back a list of field names and values for the first record satisfying the query. The call is useful for queries that return just a single record, the equivalent of a unique `FIND`, as shown:

>     RUN getRecordDetail IN gshGenManager
>              (INPUT pcQuery,
>               OUTPUT pcFieldList ).

> The procedure takes the following parameters:

> - `INPUT pcQuery (CHARACTER)` — The query string, beginning with `FOR` `EACH` followed by the database table name.

> - `OUTPUT pcFieldList (CHARACTER)` — A specially formatted list of field names and values for the matching record. What is returned is a `CHR(3)`-delimited list of `<table.field>` name and value pairs. In other words, each field name (qualified by the table name) is followed by `CHR(3)`, followed by the field’s formatted string value, followed by another `CHR(3)`, and so on. The record’s database `ROWID` is also returned, at the end of the list, in the format `ROWID`(`<table>`) `CHR(3)` `<table ROWID>`.

> Here is a test procedure for `getRecordDetail`. It includes `globals.i`, so that the manager handle is available, defines a query to retrieve the first `Customer` record, and displays the results, as shown:

>     /* testRecordDetail.p -- test procedure for the getRecordDetail procedure
>        in the General Manager API. */

>     {src/adm2/globals.i}
>     DEFINE VARIABLE pcQuery    AS CHARACTER  NO-UNDO.
>     DEFINE VARIABLE cFieldList AS CHARACTER  NO-UNDO.
>     DEFINE VARIABLE iField     AS INTEGER    NO-UNDO.
>         pcQuery = 'FOR EACH Customer where CustNum = 1'.
>         RUN getRecordDetail IN gshGenManager
>              (INPUT pcQuery,
>               OUTPUT cFieldList ).
>         DO iField = 1 TO NUM-ENTRIES(cFieldList, CHR(3)) BY 2:
>             DISPLAY ENTRY(iField, cFieldList, CHR(3))     FORMAT "x(30)"
>                     ENTRY(iField + 1, cFieldList, CHR(3)) FORMAT "x(40)"
>                 WITH FRAME F 21 DOWN.
>             DOWN WITH FRAME F.
>         END.

> Figure 6–8 shows what the procedure’s output looks like.

> Figure 6–8: Output of testRecordDetail.p

> Note the `ROWID` value at the end of the list. You can apply the Progress `TO-ROWID` function to this string to turn it back into a proper `RowID` data type.

> As another example of how this call could be useful, consider the `translatePhrase` function described earlier. One of the parameters is the language object ID for the language to translate into. If what you want is the current language, you just pass in 0. But if you want some other language, you can use `getRecordDetail` to retrieve the `language_obj` field for the language if you know the Where clause to construct to retrieve the record you want. In this case:

>     FOR EACH gsc_language Where language_code = “French”

> This query yields the results shown in Figure 6–9. The first field value is the language object ID, which you can convert to native `DECIMAL` form and pass in to another call that needs it.

> Figure 6–9: FOR EACH query results

> Keep in mind that because this is a general-purpose call, no caching of information is possible. Every query will result in an AppServer call in a distributed application. But also keep in mind that the call shields you from having to worry about the code needed to access the data on the AppServer, as long as the database you need is connected on the default AppServer whose handle is in `gshAstraAppServer`.

> This series of examples should give you a good idea of how to take advantage of the Progress Dynamics managers to extend their default behavior to satisfy the needs of you application, and to help you integrate existing applications into a new Progress Dynamics application.

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