| 1 | Object description information | Input | Char(*) |
| 2 | Control value information | Output | Char(*) |
The Storage Extension exit program provides the capability of restoring the entire object using a storage extension, that is, restoring objects that were saved using *FREE, or freed through an application programming interface. (*DOC and *STMF files are freed through an API, not through save using *FREE.)
Note: To use this exit program, you need the Media and Storage Extension feature of the IBM® i operating system.
If there is any program registered against exit point format name EX400200 of this exit point, then any programs registered against exit point format name EX400300 will not be called. Therefore, if you are installing your application and you are registering it against exit point format EX400300, verify that no programs are registered against exit point format name EX400200. If there are any, notify the user that it needs to be disabled before the application will work. Do not simply deregister programs from exit point format name EX400200 when installing your application because it may impact other applications.
Storage extension refers to those objects (and the CL commands that refer to those objects) saved from disk using the *FREE option on the storage parameter. These saved objects free disk space by storing a copy of the entire object and keeping only the object headers on disk. Currently, only file, document, and stream objects are supported.
Objects may be scheduled to be saved from disk when they are not referred to for a specified amount of time. When the objects are saved, the object data is saved and the object headers remain on disk. When this object is referred to, the operating system calls the exit program for object restoration through the registration facility. (For information about registering an exit point with the registration facility and adding an exit program to an exit point, see Registration Facility APIs. The exit point format EX400200 supports only one exit program.)
When the user exit program is given control, it verifies that the object was saved. If the exit program has the object saved and wants to restore it, the exit program restores the object data and returns a control value to the IBM i operating system indicating that the object was restored through the control value information. If the exit program does not have the object saved, it returns a control value to IBM i indicating that the object was not restored through the control value information.
When an object is determined to be saved using *FREE, each program that is registered against exit point format name EX400300 will be called (as long as no programs are registered against EX400200) with an indicator that it is asking for a date/time stamp of the most recent version of the object that the exit program has.
After all programs are called, the exit program that specified the most recent date/time stamp will be called again with the indicator to restore the object.
After the user exit program is given control and restores the object that was suspended, it should return the control value to the IBM i operating system indicating that the object was restored through the control value information.
None.
Information about the object that the exit program will attempt to restore from storage extension. For details, see Format of Object Description Information (EX400200,EX400300).
Information about whether the exit program restored the object requested or did not have the object stored in storage extension. For details, see Format of Control Value Information.
The following table shows the format of the object description information. For a description of the fields in this format, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of object description information |
| 4 | 4 | BINARY(4) | Length of control value information |
| 8 | 8 | CHAR(10) | Object name |
| 18 | 12 | CHAR(10) | Object library name |
| 28 | 1C | CHAR(10) | Object type |
| 38 | 26 | CHAR(10) | Member name |
| 48 | 30 | CHAR(10) | Job name |
| 58 | 3A | CHAR(10) | User name |
| 68 | 44 | CHAR(6) | Job number |
| 74 | 4A | CHAR(2) | Reserved |
| 76 | 4C | BINARY(4) | Offset to path name structure |
| 80 | 50 | BINARY(4) | Length of path name structure |
| 84 | 54 | CHAR(10) | Request type |
| 94 | 5E | CHAR(13) | Date/time stamp |
| CHAR(*) | Path name structure | ||
Date/time stamp. The most recent date/time stamp that the other exit programs have specified as their most recent copy of the suspended object. If this is the first exit program being called, or no other exit program has a copy of the suspended object to be restored, then this field will be set to blanks. This field will be blanks when passed for exit format EX400200. This field will be of the following CYYMMDDHHMMSS format:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YYMMDD | The date (year, month, day format). |
| HHMMSS | The time (hours, minutes, seconds format). |
Job name. The job name.
Job number. The job number associated with the job name and user identifier.
Length of control value information. The length, in bytes, of the control value information.
Length of the path name structure. The length, in bytes, of the path name structure. This field will be set to zero if the object does not have a path name structure passed.
Length of object description information. The length, in bytes, of the object description information.
Member name. The member within the file that caused the exception.
Object library name. The library name of the object being referred to. The special value is:
| *PATH | The path name structure will contain the object information. |
Object name. The name of the object that is being referred to and that causes an exception. The user exit program checks if it has this object saved to storage extension. The special value is:
| *PATH | The path name structure will contain the object information. |
Object type. The standard object types known to the system. Currently, only the following object types are supported:
| *FILE | File object (object name and library fields will contain object name information). |
| *DOC | Document object (path name structure will contain object name information). |
| *STMF | Stream file object (path name structure will contain object name information). |
Offset to path name structure. The offset, in bytes, to the path name structure that is passed containing object pathname and translation information. This field will be set to zero if the object does not have an path name structure.
Path name structure. The path name structure and translation information for the suspended object. The path name structure contains information such as CCSID, country or region, and language. For more information on this structure, see Path name format.
Request type. The type of request to the exit program from the operating system. This field will always be *RESTORE for exit format EX400200. Possible values are:
| *RESTORE | The exit program is getting called to restore the object. |
| *DATETIME | The exit program is getting called to return the latest date/time stamp of the most recent save operation of the suspended object. Note that IBM i does not restrict the called exit program from actually restoring the object when called for a date/time stamp, but it will only be a degradation in performance due to an extra restore of the object. |
Reserved. An unused field.
User name. The user identifier of the caller.
The following table shows the format of the control value information. For a description of the fields in this format, see Control Value Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Object restoration information |
| 1 | 1 | CHAR(13) | Date/time stamp |
Date/time stamp. This field should be set by the exit program when the request type specified in the Format of Object Description Information (EX400200,EX400300) is *DATETIME. This field is used by the operating system to determine which registered exit program will be called again to restore the object. The field is only used when programs registered under exit point format EX400300 are called. The determination is based on which exit program indicates the most recent copy of the suspended object. This field will be of the following CYYMMDDHHMMSS format:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YYMMDD | The date (year, month, day format). |
| HHMMSS | The time (hours, minutes, seconds format). |
Object restoration information. Whether or not the object was successfully restored or whether the exception should be resignaled. If this field contains a value that is not valid, the value is ignored and message CPD6705 is issued. The default for this field is 0. Valid values are:
| 0 | The object has not been restored or was not asked
to be restored through the request type field. Note: This field should always be left by the exit program as 0 when the request type specified in the Format of Object Description Information (EX400200,EX400300) is *DATETIME. |
| 1 | The object has been restored. Note: If the user exit program specifies a 1 for this field and it did not attempt to (or successfully) restore the entire object, message CPD6704 is signaled. |
| Message ID | Error Message Text |
|---|---|
| CPD6704 D | Error detected using program &1 in &2. |
| CPD6705 D | Incorrect user exit control value specified. |
[ Back to top | >Backup and Recovery APIs | APIs by category ]