MSGFILE

Derivation: MeSsaGe FILE

MSGFILE specifies the ddname of the file where all runtime diagnostics and reports generated by the RPTOPTS and RPTSTG run-time options are written. MSGFILE also specifies the ddname for CEEMSG and CEEMOUT callable services.

Non-CICS default: MSGFILE=((SYSOUT,FBA,121,0,NOENQ),OVR)
CICS® default: MSGFILE is ignored under CICS.


Syntax

>>-MSGFILE--=--(--(--ddname--,--recfm--,--lrecl--,--blksize----->

      .-NOENQ-.        .-OVR----.      
>--,--+-ENQ---+--)--,--+-NONOVR-+--)---------------------------><

ddname: The ddname of the runtime diagnostics file.
recfm: The default record format (RECFM) value for the message file. recfm is used when this information is not available either in a file definition or in the label of an existing file. The following values are acceptable: F, FA, FB, FBA, FBS, FBSA, U, UA, V, VA, VB, and VBA.
lrecl: The default record length (LRECL) value for the message file. lrecl is used when this information is not available either in a file definition or in the label of an existing file. lrecl is expressed as bytes of storage.
The lrecl value (whether from MSGFILE or from another source) cannot exceed the blksize value, whose maximum value is 32760. For variable-length record formats, the lrecl value is limited to the blksize value minus 4.
blksize: The default block size (BLKSIZE) value for the message file. blksize is used when this information is not available either in a file definition or in the label of an existing file. blksize is expressed as bytes of storage.
blksize (whether from MSGFILE or from another source) cannot exceed 32760.
NOENQ: Serialization around writes to the message file destination specified ddname are not performed.
ENQ: Specifies that serialization is performed around writes to the ddname specified.
OVR: Specifies that the option can be overridden.
NONOVR: Specifies that the option cannot be overridden.

CICS considerations

This runtime output under CICS is directed to a transient data queue named CESE.

z/OS® UNIX considerations

The MSGFILE option specifies the ddname of the diagnostic file for the enclave. When multiple threads write to the message file, the output is interwoven by line. To group lines of output, serialize MSGFILE access (by using a mutex, for example).

When z/OS UNIX is available and the MSGFILE option specifies a ddname nominating a POSIX file, Language Environment uses POSIX services to write the message file. A ddname nominates a POSIX file using the keyword PATH=.

z/OS UNIX must be available on the underlying operating system for the MSGFILE option to write to a POSIX file. If the ddname nominates a POSIX file and z/OS UNIX is not present, then Language Environment tries to dynamically allocate an MVS™ file to be used as the message file.

If the message file is allocated (whether POSIX or z/OS), Language Environment directs the output to this file. If the current message file is not allocated, and the application carries out a fork()/exec, spawn(), or spawnp(), Language Environment checks whether File Descriptor 2 exists. If it does exist, then Language Environment uses it; otherwise, Language Environment dynamically allocates the message file to the POSIX file system and attempts to open the file SYSOUT in the current working directory; or, if there is no current directory, then in the directory /tmp.

Usage notes

The ENQ suboption should only be used where multiple Language Environment® environments are running in the same address space and are sharing the same MSGFILE destination. An example would be a batch job which uses ATTACH to create some number of subtasks. Each of these tasks is potentially a distinct Language Environment environment all running with the same default MSGFILE parameters. In this example, each of these environments will share the same MSGFILE destination. To avoid conflicts while writing to the shared MSGFILE destination, it is recommended that the ENQ suboption be used for each MSGFILE destination that will be shared. Using different ddname for each environment would remove the need to use the ENQ suboption.
HLL compiler options, such as the COBOL OUTDD compiler option, can affect whether your runtime output goes to MSGFILE ddname.
Use commas to separate suboptions of the MSGFILE runtime option. If you do not specify a suboption but do specify a subsequent one, you must still code the comma to indicate its omission. However, trailing commas are not required.
If you do not specify any suboptions, either of the following is valid: MSGFILE or MSGFILE().
If there is no block size in the MSGFILE runtime option, in a file definition, or in the label of an existing file, block size is determined as follows:
- For a recfm value that specifies unblocked fixed-length format records (F or FA) or undefined-format records (U or UA), the blksize value is the same as the lrecl value.
- For a recfm value that specifies unblocked variable-length format records (V or VA), the blksize value is the lrecl value plus 4.
- For a DASD device on MVS and a recfm value that specifies blocked records (FB, FBA, FBS, FBSA, VB, or VBA), the blksize value is left at 0 by Language Environment so that the system can determine the optimum blksize value.
- For a terminal and a recfm value that specifies blocked fixed-length format records (FB, FBA, FBS, or FBSA), the blksize value is the same as the lrecl value.
- For a terminal and a recfm value that specifies blocked variable-length format records (VB or VBA), the blksize value is the lrecl value plus 4.
- For all other cases, blksize has a value which gives 100 records per block if the blksize value wouldn't exceed 32760, otherwise, a value giving the largest number of records per block such that the blksize value that does not exceed 32760.
  Or, to put it another way:
  - For a recfm value that specifies blocked fixed-length format records (FB, FBA, FBS, or FBSA), the blksize value is lrecl × bfact where bfact is the largest integer not exceeding 100 such that the blksize value does not exceed 32760.
  - For a recfm value that specifies blocked variable-length format records (VB or VBA), the blksize value is (lrecl × bfact) plus 4 where bfact is the largest integer not exceeding 100 such that the blksize value does not exceed 32760.
Language Environment detects certain invalid values for the MSGFILE suboptions, namely an invalid value for recfm and a value of lrecl or blksize that exceeds 32760. A message is printed, and any incorrect values are ignored.
Invalid combinations of recfm, lrecl, and blksize values are not diagnosed by Language Environment but can cause an error condition to be detected by the system on the first attempt to write to the message file.
Language Environment does not check the validity of the MSGFILE ddname. An invalid ddname generates an error condition on the first attempt to issue a message.
Language Environment supports the use of a MSGFILE DDNAME dynamically allocated with the XTIOT, UCB nocapture, or DSAB-above-the-line options specified in the SVC99 parameters (S99TIOEX, S99ACUCB, S99DSABA flags).

C/C++ considerations: C perror() messages and output directed to stderr go to the MSGFILE destination.
Fortran considerations: To get the same message file function as with VS Fortran, specify MSGFILE(FTnnF001,UA,133) where nn is the unit number of the error unit. For more information, see the Fortran Run-Time Migration Guide.
PL/I considerations: Runtime messages in PL/I programs are directed to the file specified by MSGFILE, instead of to the PL/I SYSPRINT STREAM PRINT file.
User-specified output is still directed to the PL/I SYSPRINT STREAM PRINT file. To direct this output to the Language Environment MSGFILE file, specify MSGFILE(SYSPRINT).

For more information

For more information about the RPTOPTS and RPTSTG runtime options, see RPTOPTS and RPTSTG.
For more information about the CEEMSG and CEEMOUT callable services, see z/OS Language Environment Programming Reference.
For details on how HLL compiler options affect messages, see information about HLL I/O statements and message handling in z/OS Language Environment Programming Guide.
For more information about perror() and stderr see C message output information in z/OS Language Environment Programming Guide.
For more information about the CESE transient data queue, see z/OS Language Environment Programming Guide.