Programming considerations

The retrieval preview user exit is not called for all document retrievals. In particular, the user exit is not called for functions that use the so-called Bulk Retrieval method of retrieving documents or for server printing.

For example, running the ARSDOC GET function without specifying the -n parameter performs a bulk retrieval, and documents retrieved will not be presented to the client preview exit.

If a request is made to retrieve a large object document, care should be taken to make certain that the retrieval preview user exit does not remove any pages from the document. The large object segment size and page navigation information are based on the number of pages that existed when the document was loaded on the server. Unexpected results can occur if this information is changed. The retrieval preview user exit can be enabled for all data types, except for None.

The user-written program can be used to remove sensitive information from a document or to perform other types of data manipulation. However, because the user-written program is not used during server reprinting or bulk retrievals, the restricted data might still be accessible by the user.

When modifying the data, the format and type of the data must not be changed; only the content can be changed. For example:
  • If the format of the data is EBCDIC data with a fixed length of 133 bytes, the format must not be changed to something different, such as ASCII data delimited by the line feed character (X'0A')
  • If the data type is AFP, the document cannot be converted to some other type of data, such as PDF
When the modified data is viewed by the OnDemand Client, the format of the data and the data type that is defined in the application on the View Information page will be used to display the data. If the format or data type has changed, the document will not view properly.

The retrieval user exit point can be enabled for more than one application. However, all applications must be processed by the same user-written program (only one user-written program is supported). The system passes the name of the application that is associated with the document to the user-written program. The user-written program can perform processing based on the application or it can perform the same processing for all documents regardless of the application.

A sample user exit program arsuprep.c and header file arscsxit.h are provided by IBM®. The files are located in the /opt/IBM/ondemand/V10.5/exits directory on AIX®, in the /opt/ibm/ondemand/V10.5/exits directory on Linux, and in the \Program Files\IBM\OnDemand\V10.5\exits directory on Windows.

Return values

If the exit wants a different file presented to the user, it should set prep->OutFileName to the name of the file. This file must be formatted to agree with the specification in ArcCSXitAppl. For example, the file cannot be in variable format if the ArcCSXitAppl indicates fixed.

This file is deleted when its contents are updated to the user. The exit should set a return code of 0 (zero).