Provides control over program cancels.
call "CBL_CANCEL_PROC" using by value function
by reference parameter-block
by value cblte-cppb-userdata-length
returning status-code
01 cblt-cancel-proc-params typedef.
03 cblte-cppb-version cblt-x4-comp5. *> pic x(4) comp-5 value 0.
03 cblte-cppb-flags cblt-x4-comp5. *> pic x(4) comp-5.
03 cblte-cppb-callback cblt-ppointer *> usage procedure-pointer.
03 cblte-cppb-handle cblt-pointer *> usage pointer.
03 cblte-cppb-userdata cblt-pointer *> usage pointer.
03 cblte-cppb-priority cblt-x4-comp5. *> pic x(4) comp-5.
| 0 | Installs a cancel-routine at the default priority of 64: |
| 1 | Installs a cancel-routine at a specified priority. See the section Comments. |
| 2 | Enables a program to change the priority of a previously installed cancel routine: |
| 3 | Enables a cancel-registration to be de-installed without causing the cancel-routine to be called. |
| 4 | Enables a cancel-registration to be de-installed after causing the cancel-routine to be called. Note that the cancel-routine can detect if it is being called because of a de-install rather than a real CANCEL. |
| 0, 1 | The cancel-routine to install. |
| 2-4 | Ignored. |
| 0, 1 | The program-handle of the program to which to attach the cancel-routine, or NULL. See the discussion on program-handles in the section Comments. |
| 2 | The handle of the cancel-routine to modify registration. |
| 3, 4 | The handle returned from when function was set to either 0 or 1. This is the handle of the cancel-routine to de-register. |
| 0, 1 | User-defined data area. See discussion on user-data areas in the section Comments. |
| 2-4 | Ignored. |
| 0, 1 | The length of the cblte-cppb-userdata block, or zero. See discussion on user-data areas in the section Comments. |
| 2-4 | Ignored. |
| 0, 1 | The handle for the cancel-registration, or NULL. |
| 2 | Ignored. |
| 3, 4 | NULL. |
| 0000 | Success - The operation was performed as requested. |
| 1000 | Memory allocation error processing request. |
| 1001 | Bad handle passed to API (Registration-handle). |
| 1007 | System error (that is, any error not listed here). |
| 1009 | Bad parameter passed (in function, param, and so on). |
This routine provides a mechanism by which a COBOL program can receive notification of an impending cancel of either itself, or another COBOL program.
Such notification enables a COBOL program to finalize its use of, and deallocate, any resources it has allocated during its existence that are not already handled automatically by the COBOL run-time system or the operating system. These resources are normally those provided by the operating system or run-time system, but could also be some resource provided by another module in the application itself.
The COBOL run-time system performs notifications by processing a list (the cancel-list) which it has associated with the program being canceled. Therefore, to enable a notification, the COBOL run-time system must be instructed to create an entry in the cancel-list. Managing entries in cancel-lists is the purpose of CBL_CANCEL_PROC.
To create an entry in the cancel-list, CBL_CANCEL_PROC needs to know three things:
This information is provided to the run-time system by setting the parameter function to 0 or 1. By doing this, you create an entry in the cancel-list associated with the program cblte-cppb-handle. The entry specifies that the cblte-cppb-callback should be called when notification is due. The position in the list is determined by the value of cancel-priority.
The entry in the cancel-list created can be referenced using the value returned by the registration call in the cblte-cppb-handle parameter on exit. This enables a program to modify the registration at a later time, using this routine with function set to 2, 3 or 4; for example, you can change the priority of the registration, or remove it from the list.
A program-handle is a unique value which the COBOL run-time system associates with a cancelable entity. Therefore, all entry-points in a COBOL program share the same program-handle, as cancelling any entry-point in a COBOL program cancels all entry points in that program.
There are two basic methods of using the CBL_CANCEL_PROC routine, and the amount of work a program needs to do in order to obtain the correct program-handle depends on which method is necessary.
When a program wishes to receive a notification that it is to be canceled, it can make a local registration - usually in its "first time in" code. For this method of registration, the program need only pass NULL as a program-handle. The CBL_CANCEL_PROC routine then automatically locates the correct program-handle and creates an entry in the correct list.
Usually, the cblte-cppb-callback specified in a local registration is an entry-point in the registering program (though it doesn't have to be).
An example would be a program which allocated some resource directly from the operating system and which needed the opportunity to deallocate it before being canceled.
This is a slightly more complicated type of registration, and is used when a service program (that is, a program which manages a resource on behalf of other COBOL programs)