Intercepting files when debugging C and C++ programs

Several considerations must be kept in mind when using the SET INTERCEPT command to intercept files while you are debugging a C application.

For CICS® only: SET INTERCEPT is not supported for CICS.

For C++, there is no specific support for intercepting IOStreams. IOStreams is implemented using C I/O which implies that:
  • If you intercept I/O for a C standard stream, this implicitly intercepts I/O for the corresponding IOStreams' standard stream.
  • If you intercept I/O for a file, by name, and define an IOStream object associated with the same file, IOStream I/O to that file will be intercepted.
Note: Although you can intercept IOStreams indirectly via C/370 I/O, the behaviors might be different or undefined in C++.
You can use the following names with the SET INTERCEPT command during a debug session:
  • stdout, stderr, and stdin (lowercase only)
  • any valid fopen() file specifier.

The behavior of I/O interception across system() call boundaries is global. This implies that the setting of INTERCEPT ON for xx in Program A is also in effect for Program B (when Program A system() calls to Program B). Correspondingly, setting INTERCEPT OFF for xx in Program B turns off interception in Program A when Program B returns to A. This is also true if a file is intercepted in Program B and returns to Program A. This model applies to disk files, memory files, and standard streams.

When a stream is intercepted, it inherits the text/binary attribute specified on the fopen statement. The output to and input from the z/OS® Debugger log file behaves like terminal I/O, with the following considerations:
  • Intercepted input behaves as though the terminal was opened for record I/O. Intercepted input is truncated if the data is longer than the record size and the truncated data is not available to subsequent reads.
  • Intercepted output is not truncated. Data is split across multiple lines.
  • Some situations causing an error with the real file might not cause an error when the file is intercepted (for example, truncation errors do not occur). Files expecting specific error conditions do not make good candidates for interception.
  • Only sequential I/O can be performed on an intercepted stream, but file positioning functions are tolerated and the real file position is not changed. fseek, rewind, ftell, fgetpos, and fsetpos do not cause an error, but have no effect.
  • The logical record length of an intercepted stream reflects the logical record length of the real file.
  • When an unintercepted memory file is opened, the record format is always fixed and the open mode is always binary. These attributes are reflected in the intercepted stream.
  • Files opened to the terminal for write are flushed before an input operation occurs from the terminal. This is not supported for intercepted files.
Other characteristics of intercepted files are:
  • When an fclose() occurs or INTERCEPT is set OFF for a file that was intercepted, the data is flushed to the session log file before the file is closed or the SET INTERCEPT OFF command is processed.
  • When an fopen() occurs for an intercepted file, an open occurs on the real file before the interception takes effect. If the fopen() fails, no interception occurs for that file and any assumptions about the real file, such as the ddname allocation and data set defaults, take effect.
  • The behavior of the ASIS suboption on the fopen() statement is not supported for intercepted files.
  • When the clrmemf() function is invoked and memory files have been intercepted, the buffers are flushed to the session log file before the files are removed.
  • If the fldata() function is invoked for an intercepted file, the characteristics of the real file are returned.
  • If stderr is intercepted, the interception overrides the Language Environment® message file (the default destination for stderr). A subsequent SET INTERCEPT OFF command returns stderr to its MSGFILE destination.
  • If a file is opened with a ddname, interception occurs only if the ddname is specified on the INTERCEPT command. Intercepting the underlying file name does not cause interception of the stream.
  • User prefix qualifications are included in MVS data set names entered in the INTERCEPT command, using the same rules as defined for the fopen() function.
  • If library functions are invoked when z/OS Debugger is waiting for input for an intercepted file (for example, if you interactively enter fwrite(..) when z/OS Debugger is waiting for input), subsequent behavior is undefined.
  • I/O intercepts remain in effect for the entire debug session, unless you terminate them by selecting SET INTERCEPT OFF.
Command line redirection of the standard streams is supported under z/OS Debugger, as shown below.
1>&2
If stderr is the target of the interception command, stdout is also intercepted. If stdout is the target of the INTERCEPT command, stderr is not intercepted. When INTERCEPT is set OFF for stdout, the stream is redirected to stderr.
2>&1
If stdout is the target of the INTERCEPT command, stderr is also intercepted. If stderr is the target of the INTERCEPT command, stdout is not intercepted. When INTERCEPT is set OFF for stderr, the stream is redirected to stdout again.
1>file.name
stdout is redirected to file.name. For interception of stdout to occur, stdout or file.name can be specified on the interception request. This also applies to 1>>file.name
2>file.name
stderr is redirected to file.name. For interception of stderr to occur, stderr or file.name can be specified on the interception request. This also applies to 2>>file.name
2>&1 1>file.name
stderr is redirected to stdout, and both are redirected to file.name. If file.name is specified on the interception command, both stderr and stdout are intercepted. If you specify stderr or stdout on the INTERCEPT command, the behavior follows rule 1b above.
1>&2 2>file.name
stdout is redirected to stderr, and both are redirected to file.name. If you specify file.name on the INTERCEPT command, both stderr and stdout are intercepted. If you specify stdout or stderr on the INTERCEPT command, the behavior follows rule 1a above.
The same standard stream cannot be redirected twice on the command line. Interception is undefined if this is violated, as shown below.
2>&1 2>file.name
Behavior of stderr is undefined.
1>&2 1>file.name
Behavior of stdout is undefined.

Refer to the following topics for more information related to the material discussed in this topic.

  • Related references
  • z/OS XL C/C++ Programming Guide