Free Object (QTAFROBJ) API
| 1 | Request variable | Input | Char(*) |
| 2 | Length of request variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Free Object (QTAFROBJ) API will "suspend" a document object specified by the caller of the API. A call to this API forces the system storage that is occupied by the data portion of the specified object to be freed. Only the data portion of the objects is freed, not the descriptions of the object. This function is similar to the save with storage freed option, STG(*FREE), on the Save Document Library Object (SAVDLO) command.
The caller of this API is required to verify that the specified object has not been changed since it was last saved.
Notes:
- To use this API, you need the Media and Storage Extensions feature of the IBM® i operating system.
- For a document of type *DOC, the caller must be enrolled in the system distribution directory to use this API.
Authorities and Locks
- Object Authority
- *CHANGE
- *OBJEXIST
- Directory Authority
- *X
Required Parameter Group
- Request variable
- INPUT; CHAR(*)
The request variable that identifies the object to be suspended.
- Length of request variable
- INPUT; BINARY(4)
The length of the request variable provided. Valid values range from 48 through 32048.
- Format name
- INPUT; CHAR(8)
The format of the object information being passed to the QTAFROBJ API. The TAFO0100 format must be used for this API. See TAFO0100 Format to view the object information required to perform this API.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
TAFO0100 Format
The following table shows the object information that is required for the TAFO0100 format. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Object name |
| 10 | A | CHAR(10) | Object library |
| 20 | 14 | CHAR(10) | Reserved |
| 30 | 1E | CHAR(10) | Object type |
| 40 | 28 | BINARY(4) | Offset to path name structure |
| 44 | 2C | BINARY(4) | Length of path name structure |
| CHAR(*) | Path name structure | ||
Field Descriptions
Length of the path name structure. The length, in bytes, of the path name structure. This field must be set to zero if the object does not have a path name structure passed. Valid values are 0 and 48 through 32048.
Object library. The library name of the object to be freed. The special value is:
| *PATH | The path name structure contains the object information. |
Object name. The name of the object to be freed by the API. The special value is:
| *PATH | The path name structure contains the object information. |
Object type. The type of object specified to be freed by the API. Possible values follow:
| *DOC | The object to be suspended is a document. |
| *PATH | The path name structure will contain the object information. |
Offset to path name structure. The offset from the start of the structure, in bytes, to a path name structure that contains object path name and translation information. This field must be set to zero if the object does not have a path name structure. Valid values are 0 and 48 through 32048.
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. The path name must be in the library file system format; for example, /QSYS.LIB/QDOC.LIB/DOC1.DOC
Reserved. An ignored field. This field must be set to blanks.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3C4B E | Value not valid for field &1. |
| CPF3C4C E | Value not valid for field &1. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF6708 E | Command ended due to error. |
| CPF67C2 E | Path name structure field &7 not valid. |
| CPF67C4 E | Object &1 type &2 in library &3 not freed. Object in use. |
| CPF67C5 E | Object &1 type &2 in library &3 not freed. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V4R3
[ Back to top | Backup and Recovery APIs | APIs by category ]