Free Object (QTAFROBJ) API

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:

1. To use this API, you need the Media and Storage Extensions feature of the i5/OS.
2. 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.

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:

Object name. The name of the object to be freed by the API. The special value is:

Object type. The type of object specified to be freed by the API. Possible values follow:

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