SAVE CACHE statement

Saves the schema cache of a database to an operating system file. Subsequent sessions can then share the same cache by using the Schema Cache File (-cache) parameter.

Syntax

SAVE CACHE 
    { CURRENT | COMPLETE }
    {database-name| VALUE ( char-expr ) }
  TO
    {pathname|  VALUE ( char-expr ) }
[ NO-ERROR ]

CURRENT

Specifies that only the portion of the schema cache that applies to referenced tables is saved to the file. By using this option you can tailor a small schema cache file for an application that does not use all the tables in the database.

COMPLETE

Specifies that the complete schema cache for the database is saved to the file. If you use this option, the client process builds a complete schema cache in memory including template records and all trigger information for every table in the database.

database-name

Specifies the literal logical name of a currently connected OpenEdge database.

pathname

Specifies the literal pathname of an operating system file to hold the schema cache. In Windows, the pathname cannot contain characters outside of the non-Unicode code page. See OpenEdge Development: Internationalizing Applications for more information about Unicode and code pages.

VALUE (char-expr)

Returns the corresponding literal database name or pathname specified by the character expression in char-expr.

NO-ERROR

Suppresses ABL errors or error messages that would otherwise occur and diverts them to the ERROR-STATUS system handle. If an error occurs, the action of the statement is not done and execution continues with the next statement. If the statement fails, any persistent side-effects of the statement are backed out. If the statement includes an expression that contains other executable elements, like methods, the work performed by these elements may or may not be done, depending on the order the AVM resolves the expression elements and the occurrence of the error.

To check for errors after a statement that uses the NO-ERROR option:

• Check the ERROR-STATUS:ERROR attribute to see if the AVM raised the ERROR condition.
• Check if the ERROR-STATUS:NUM-MESSAGES attribute is greater than zero to see if the AVM generated error messages. ABL handle methods used in a block without a CATCH end block treat errors as warnings and do not raise ERROR, do not set the ERROR-STATUS:ERROR attribute, but do add messages to the ERROR-STATUS system handle. Therefore, this test is the better test for code using handle methods without CATCH end blocks. ABL handle methods used in a block with a CATCH end block raise ERROR and add messages to the error object generated by the AVM. In this case, the AVM does not update the ERROR-STATUS system handle.
• Use ERROR-STATUS:GET-MESSAGE( message-num ) to retrieve a particular message, where message-num is 1 for the first message.

If the statement does not include the NO-ERROR option, you can use a CATCH end block to handle errors raised by the statement.

Some other important usage notes on the NO-ERROR option:

• NO-ERROR does not suppress errors that raise the STOP or QUIT condition.
• A CATCH statement, which introduces a CATCH end block, is analogous to a NO-ERROR option in that it also suppresses errors, but it does so for an entire block of code. It is different in that the error messages are contained in a class-based error object (generated by the AVM or explicitly thrown), as opposed to the ERROR-STATUS system handle. Also, if errors raised in the block are not handled by a compatible CATCH block, ON ERROR phrase, or UNDO statement, then the error is not suppressed, but handled with the default error processing for that block type.
• When a statement contains the NO-ERROR option and resides in a block with a CATCH end block, the NO-ERROR option takes precedence over the CATCH block. That is, an error raised on the statement with the NO-ERROR option will not be handled by a compatible CATCH end block. The error is redirected to the ERROR-STATUS system handle as normal.
• If an error object is thrown to a statement that includes the NO-ERROR option, then the information and messages in the error object will be used to set the ERROR-STATUS system handle. This interoperability feature is important for those integrating code that uses the traditional NO-ERROR technique with the newer, structured error handling that features error objects and CATCH end blocks.

Example

This procedure saves the complete schema cache for each database that you specify in the current working directory, and displays any error messages associated with connecting or saving the cache:

r-schcsh.p

DEFINE VARIABLE db-name AS CHARACTER NO-UNDO FORMAT "x(12)" INITIAL ?.
DEFINE VARIABLE icnt    AS INTEGER   NO-UNDO.

DO WHILE db-name <> "":
 SET db-name LABEL "Database Name" 
   WITH FRAME A SIDE-LABELS TITLE "Save Cache" VIEW-AS DIALOG-BOX.
 IF db-name <> "" THEN 
   CONNECT VALUE(db-name) -1 NO-ERROR.
 ELSE LEAVE.

 IF NOT ERROR-STATUS:ERROR THEN DO:
   SAVE CACHE COMPLETE VALUE(db-name) TO VALUE(db-name + ".csh") NO-ERROR.
   IF NOT ERROR-STATUS:ERROR THEN
     MESSAGE "Saved schema cache for" db-name "in" db-name + ".csh.".
   ELSE DO:
     BELL.
     DO icnt = 1 TO ERROR-STATUS:NUM-MESSAGES:
       MESSAGE ERROR-STATUS:GET-MESSAGE(icnt) VIEW-AS ALERT-BOX.
     END.
   END.
 END.
 ELSE DO:
   BELL.
   DO icnt = 1 TO ERROR-STATUS:NUM-MESSAGES:
     MESSAGE ERROR-STATUS:GET-MESSAGE(icnt) VIEW-AS ALERT-BOX.
   END.
 END.
 DISCONNECT VALUE(db-name) NO-ERROR.
END.

Notes

• The schema cache is saved to the file in a binary format that is portable across machines.
• For information on using an existing schema cache file, see OpenEdge Data Management: Database Administration. For information on the Schema Cache File (-cache) startup parameter, see OpenEdge Deployment: Startup Command and Parameter Reference.
• Any schema changes to the database make the saved cache invalid. If the schema cache file is invalid when the AVM tries to access it, the AVM displays a warning message, ignores the file, and reads the required schema cache from the database.
• To set up your database environment to use the CURRENT option, you only have to connect to the database and read from the tables that compose the schema you want to save. This is sufficient for the SAVE CACHE statement to save all parts of each table in the schema, including template records and trigger information. If you want to save a different subschema of the database, you must disconnect and then reconnect to the database before reading the tables for that subschema.
• For a DataServer, the AVM saves the schema cache for the entire schema holder database. You cannot save the schema cache for a non-OpenEdge database separately. For more information on schema cache files for DataServers, see the OpenEdge DataServer Guides (OpenEdge Data Management: DataServer for Microsoft SQL Server, OpenEdge Data Management: DataServer for ODBC, and OpenEdge Data Management: DataServer for Oracle).

See also

CONNECT statement, ERROR-STATUS system handle