| Debugger I/O Exit Routines |
The installation tape also contains sample debugger
exit routines. These are in the sample source libraries LSU MACLIB (CMS) and
SASC.SOURCE (OS/390), with member names L$UDBIN and L$UDBOUT. These samples
can provide useful information for writing your own exit routines.
When the output exit routine receives control for initialization,
register 1 points to the following parameter block:
Word 2 addresses an 8-byte area. The first 4 bytes
of this area contain the address of a debugger subroutine that is called asynchronously
to present an attention interrupt. This subroutine is called the attention
simulation routine. The second 4 bytes contain a value that must be passed
to the attention simulation routine when a simulated attention is to be generated.
See Attention Handling.
Word 3 addresses a flag byte. On entry, this byte is
0. If the output exit sets this byte to a nonzero value, then the debugger
recognizes only the attention interrupts that are generated by a call to the
attention simulation routine.
The values from the CRAB user words are probably 0 because
the debugged program has not yet received control . However, the values may
not always be 0.
After initialization, the output exit routine returns
four values. These values must be returned in registers 15, 0, 1, and 2. The
values are the new values for the CRAB user words. The CRAB user words are
used to communicate between the output exit routine and the input exit routine.
For example, you may return the address of a communication area for CRABUSR1.
Values for CRAB user words that you do not plan to use must be returned unchanged.
Do this by loading the appropriate registers from the input parameter block.
This indicates that the output does not need to use the word or words and
allows some other part of the system to use them. The returned values from
registers 15, 0, 1, and 2 are placed in the CRAB user words of the program
being debugged.
If the debugger is used in batch mode, the debug log
file always opens even if the output exit routine is present, which may suppress
all output to the log file. An OPEN failure terminates debugger activity.
Therefore, under OS/390 in batch mode, you should provide a JCL statement
for DBGLOG, even if the output exit suppresses all output to it. You can use
a DUMMY DD statement.
When the attention simulation routine is called, the following
values must be in the general registers:
The output exit routine receives control when an attention
prompt is needed. The attention prompt is usually issued by the debugger
when an attention interrupt is pending, and then the user issues a second
attention interrupt. In the usual case (that is, when the I/O exits are not
used), the debugger prompts the user to decide whether to continue execution
or to abort the program. When the I/O exits are in use, the output exit routine
must decide how to handle the second interrupt.
When the output exit routine receives control for an
attention prompt call, register 1 points to the following parameter block:
The exit returns one of the following return codes:
Note that the output exit routine receives an attention
prompt call in response to a simulated attention. An output exit routine
that supports simulated attentions should be prepared to handle this situation.
The input exit routine receives control for initialization after
the output exit initialization call. The output exit routine may be (and probably
is) called multiple times before the input exit routine is invoked.
When the input exit routine receives control for initialization,
register 1 points to the following parameter block:
The values from the CRAB user words are those that are
set by output exit initialization, those that are set by an assembler routine
in the program itself that is invoked before any debugger input is wanted,
or they may be 0 if no output exit routine is present. However, the values
may not always be 0 in the last case.
After initialization, the input exit routine returns
0 in register 15 to indicate successful initialization. If a nonzero value
returns, the debugger assumes that the input exit routine is not to be invoked
again, even for termination.
Note that if the input exit routine does its own terminal
I/O, it must also generate any necessary prompt. The Cdebug: prompt is only generated when the input exit routine is not
used.
When
the output exit routine receives control for a normal call, register 1 points
to the following parameter block:
The output exit routine can choose how to use the current
output line. Thus, it may write it to a file, send it to another user ID,
save it for later access by the C program proper, discard it, or do any combination
of these things. Note that if it does save the current output line for later
access by another program, the output exit routine must copy the actual message
text and not just save the pointer to it. This is because the storage that
contains the message may have been reused or it may be inaccessible when the
C program receives control again.
In addition to its own use of the line, the output exit
routine controls the debugger's use of the line. It has the following three
choices:
The output exit routine indicates its choice by the
values that it returns in register 15 and register 0.
The return value in register 15 is the address of the
output line to be written or 0 (C NULL) when no line is to be written. If
the original line is to be written, register 15 should be set to the second
input parameter. (Recall that the first parameter is call type.) If a new
or modified line is to be written, register 15 should be set to its address.
Any nonaddress bits in register 15 must be set to 0. The instruction LA 15,0(,15)
accomplishes this. Note that if the output exit routine decides to edit the
original line, it must copy the line to a work area. The original line may
be a constant string in read-only storage. Attempting to modify the original
line directly has unpredictable consequences. Any new or modified line must
be delimited by the C string delimiter of hex 00. Also note that the original
line may not be null terminated. The length of the output line should always
be obtained from the parameter list. Finally, note that the maximum length
of a new line is 255 bytes. Longer lines are truncated at this length.
In addition to the value it returns in register 15,
the output exit routine must always return a second value in register 0. This
second value is for the convenience of assembler callers, which otherwise
need a translate table or loop to determine the length of a new or modified
line. C callers can use strlen.
This value must be the length of the output line (excluding the delimiter)
or 0 when no line is to be written. If the original line is to be written,
register 0 is set to the third input parameter. If a new or modified line
is to be written, register 0 is set to its length.
Note that the output exit routine is not called for
terminal output that is caused by the operation of a CMS EXEC or TSO CLIST
that is invoked via the debugger EXEC interface (for instance, REXX SAY statements).
When
the input exit routine receives control for a normal call, register 1 points
to the following parameter block:
Whenever it is called for a normal call, the input exit
routine should either provide a command line or tell the debugger to read
a command line from its standard input file (usually your terminal).
To tell the debugger to read a command line from its
standard input file, the input exit routine returns values of 0 in both register
15 and register 0. If the input exit routine provides a command, it must set
register 15 to the address of the command. Any nonaddress bits that are in
register 15 must be set to 0; the instruction LA 15,0(,15) accomplishes this.
The command must end with a C new-line character (hex 15), followed by the
standard C string delimiter (hex 00). If the command includes characters that
a user cannot type from the terminal (except for the new-line character and
delimiter described above), the results are unpredictable. Register 0 must
be set to the length of the command, including the new-line character but
excluding the string delimiter.
Any debugger commands can be provided. They are treated
as if they were read from the standard debugger input file.
Note that the input exit routine is not called for terminal
input caused by the operation of a CMS EXEC or TSO CLIST invoked via the debugger
EXEC interface (for instance, CLIST READ statements).
When
the output exit receives control for termination, register 1 points to the
following parameter block:
The output exit routine should perform any necessary
cleanup at this time and set a return code of 0 to indicate successful termination.
If problems are encountered, recall that an abend can terminate the debugger
and the user program. A message, followed by return code 0, may be preferable.
The input and output exit routines can be terminated
in either order. Termination can occur because of termination of the user
program or termination of the debugger. If the debugger or the program that
is being debugged terminates abnormally, no termination calls are made to
the exit routines. However, remember that a program check in the user program
is usually trapped by the debugger and does not cause termination of your
program.
When
the input exit routine receives control for termination, register 1 points
to the following parameter block:
The input exit routine should do any necessary cleanup
at this time and set a return code of 0 to indicate successful termination.
If problems are encountered, recall that an abend can terminate the debugger
and the user program. A message, followed by return code 0, may be preferable.
The input and output exit routines can be terminated
in either order. Termination can occur because of termination of the user
program or termination of the debugger.
Copyright © 2001
by SAS Institute Inc., Cary, NC, USA. All rights reserved.
