This routine is used to install and uninstall file I/O handlers. The routine gives you the ability to redirect file I/O operations to other, separate COBOL programs (handlers) that perform file I/O operations in addition to, or instead of the original operation.
For example, you can augment a file I/O operation to act on an additional file without rewriting the original application. C$REDIRECT specifies the name of the handler(s) that performs the additional operations. The handler is simply a COBOL program. This feature is activated or deactivated by calling C$REDIRECT. Information is passed to the handler program using standard COBOL linkage items. Each program has its own set of I/O handlers. This means that only the module (or subprogram) calling C$REDIRECT is affected.
CALL "C$REDIRECT"
USING HANDLER-FUNCTION, HANDLER-VERSION, HANDLER-NAME,
[PREVIOUS-HANDLER-NAME],
GIVING HANDLER-STATUS
| HANDLER-FUNCTION any numeric value | This parameter has three possible values, HANDLER-FUNCTION-PRE, HANDLER-FUNCTION-REPLACE, and HANDLER-FUNCTION-POST (defined in filesys.def). |
| HANDLER-VERSION any numeric value | Specifies the version of the linkage items to be passed to the handler program (defined in filesys.def). The linkage items are defined in handler.cpy. If later releases change the format of the linkage items, you can use HANDLER-VERSION to specify which version of the linkage items to use. Currently, the only legal values for this parameter are 1 and 2. |
| HANDLER-NAME PIC X(n) | Specifies the name of the handler program to be installed. Use NULL to uninstall a handler that has been previously installed. |
| PREVIOUS-HANDLER-NAME PIC X(n) (optional) | After a successful call to C$REDIRECT, this data item holds the name of the previously installed HANDLER-FUNCTION. It will contain spaces if there was no previous handler of this type. |
| HANDLER-STATUS signed numeric value (optional) | After a call to C$REDIRECT, this data item contains the status of the action. A 1 indicates that the install or uninstall action has succeeded and 0 indicates failure. Possible reasons for failure include an unsupported HANDLER-VERSION or an unsupported operation version. |
C$REDIRECT allows you to install as many as three discrete handlers:
These handlers may be used together in any combination, but each must be installed with a separate call to C$REDIRECT. All standard file I/O statements trigger the installed handlers (standard file I/O statements include: OPEN, CLOSE, READ, READ NEXT, READ PREVIOUS, WRITE, REWRITE, DELETE, DELETE FILE, START, COMMIT, and ROLLBACK). Information is passed to the handlers via standard COBOL linkage items. These items are described in the file handler.cpy that is installed with the ACUCOBOL-GT development system. Once a handler is installed, all file I/O for all files is redirected through the handler.
This routine can be used with the SORT and MERGE statements. The I/O handlers are used on the files listed in the USING and GIVING phrases when these verbs execute implicit OPEN, READ, NEXT, WRITE, AND CLOSE operations. In this situation, the handlers will be called more than once for each execution of the verb.
When an installed handler executes, it can return its status via the linkage item HANDLER-STATUS-CODE. This item is meant to return the standard COBOL file status code that is normally returned by a file operation. The value returned is made available in the file's status variable. The set of codes used is up to the developer, as long as they follow these rules:
The first handler to return an unsuccessful status code will be the last portion of the file operation to be executed, whether the remaining operation is the regular file operation or another handler. For example, a "pre" handler returning an error will preclude the execution of the normal file operation (or a "replace" handler, if defined) and the "post" handler, if defined. Declaratives are run as appropriate when a handler returns an error.