.COBRK - specify co-routine for break handling.

Alternate Entry Name: _COBRK

Usage:

B:
   count = .cobrk(fcv, quit_count);

C:
   int _cobrk(void *fcv, int quit_count);

Where:

fcv: identifies a co-routine to be invoked when the BREAK key is pressed.
quit_count: is the maximum value of the break counter. If this is a positive integer, it will be used for the maximum number of breaks that can be pending at one time. If "quit_count" is -1, .COBRK will not clear the accumulated break count; otherwise, this count is set to zero, indicating no pending breaks. If "quit_count" is not positive or -1, results are undefined.
count: gives the value that the accumulated break count had before the call to .COBRK.

Description:

.COBRK establishes a co-routine that is invoked if and when the user presses the terminal BREAK key. Once .COBRK has been used to establish a break-handler, pressing BREAK has the effect of

call(fcv,state);

where "fcv" is the co-routine identifier passed to .COBRK.

The "state" argument that is passed to the break-handling co-routine is a pointer to a 26 word vector. The first 25 words give the machine state of the program at the time BREAK was pressed (24 words of registers plus one word for the IC and I).

The 26th word (state[25]) is called the "break mask word", and it indicates what should happen if the user presses BREAK again, while the break-handling co-routine is executing. If the break mask word is non-zero, such breaks will be "masked": the system will maintain a count of how many times the user press BREAK, but there will be no apparent interruption in the break-handling co-routine's execution. Breaks are not masked if the break mask word is zero. When your break-handling co-routine is called, the break mask word will be non-zero.

When your break-handling co-routine finishes execution, it can do one of several things.

It can do a normal "return". This will go back to the co-routine that was interrupted by the BREAK. The break mask word will automatically be set to zero, so if the user presses BREAK again, the break-handling routine will be called again.
It can do a DETACH to the co-routine that was interrupted by the BREAK. This is like a "return", but if another BREAK comes in, the break-handling co-routine will resume execution from the point of the DETACH rather than its beginning. Again, the break mask word is automatically set to zero.
It can forget about the co-routine that was interrupted by the BREAK and transfer to some other part of the program. If it does this, the break-handler should set "state[25]" to zero explicitly, since it won't happen automatically. This should be the last thing the break-handler does before the transfer. Otherwise, there is a possibility of an unmasked BREAK interrupting the break-handling co-routine, leading to undefined results.

If the co-routine that was interrupted by BREAK is ever to be invoked again, you must save its 25 state words in some safe storage area before unmasking the program. Before re-invoking the interrupted co-routine, you must restore its "state" vector with these 25 state words. If your break processing has modified any other features of the program state that the interrupted co-routine may depend upon (e.g. the current read and write units), you must restore these features as well.

The B library keeps a count of the number of times BREAK is pressed. If this count exceeds "quit_count", the default break handler is invoked. This handler will terminate your program by calling EXIT. The break count and the break limit are the same count and limit maintained by NOBRKS, so NOBRKS can be used to set and/or retrieve these values. The accumulated count is only reset by a call to .COBRK or NOBRKS specifying a new limit.

It is best to keep break-processing to a minimum. If the system is kept masked for 10 consecutive breaks, the library will abort the program.

.COBRK - specify co-routine for break handling.

Usage:

Where:

Description:

See Also: