MSGFILE

Derivation: MeSsaGe FILE

The default value for non-CICS applications is MSGFILE(SYSOUT,FBA,121,0,NOENQ).

MSGFILE is ignored under CICS®.

Syntax

>>-MSGFile--(--+--------+--,--+-------+--,--+-------+--,-------->
               '-ddname-'     '-recfm-'     '-lrecl-'      

                   .-NOENQ-.      
>--+---------+--,--+-------+--)--------------------------------><
   '-blksize-'     '-ENQ---'      

ddname

The ddname of the message file where Language Environment directs the information listed above.

recfm

The record format (RECFM) for the message file. recfm is used when this information is not available either in a data set definition or in the label of an existing data set. The following record formats are acceptable: F, FA, FB, FBA, FBS, FBSA, U, UA, V, VA, VB, and VBA.

lrecl

The record length (LRECL) for the message file. lrecl is used when this information is not available either in a data set definition or in the label of an existing data set. lrecl is expressed as bytes of storage. The lrecl cannot exceed blksize. For variable-length record formats, the lrecl is limited to blksize minus 4.

blksize

The block size (BLKSIZE) for the message file. blksize is used when this information is not available either in a data set definition or in the label of an existing data set. blksize is expressed as bytes of storage and cannot exceed 32760.

NOENQ

Specifies that no serialization is performed on ddname.

ENQ

Specifies that serialization is performed on the ddname specified in case multiple Language Environment environments are running in the same address space and sharing the same message file.

CICS consideration

• MSGFILE output under CICS is directed to a transient data queue named CESE.

z/OS UNIX considerations

• When multiple threads write to the message file, the output is interwoven by line. To group lines of output, the application must serialize its own output.
• 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 calls fork()/exec(), spawn(), or spawnp(), Language Environment checks if file descriptor 2 (fd2) exists.
  • If fd2 exists, Language Environment uses it.
  • If fd2 does not exist, Language Environment dynamically allocates the message file to the POSIX file system and attempts to open the file SYSOUT in the current working directory. If there is no current directory, SYSOUT is opened in the directory /tmp.

Usage notes

• Under most circumstances, the NOENQ suboption is sufficient and provides better performance. The ENQ suboption is only needed when multiple Language Environment environments are running in the same address space and share the same message file.

  An instance when ENQ might be needed is a batch job that uses ATTACH to create sub-tasks. Each of the sub-tasks is potentially a distinct Language Environment environment, all running with the same default MSGFILE parameters. In this example, each of these environments shares the same message file.

  To avoid conflicts while writing to the shared message file, use the ENQ suboption. Using a different ddname for each environment can remove the need to use the ENQ suboption.

• Compiler options, such as the COBOL OUTDD compiler option, can affect if your runtime output goes to MSGFILE ddname.
• If there is no blksize in the MSGFILE runtime option, in a data set definition, or in the label of an existing data set, the block size is determined as follows:
  • If recfm specifies unblocked fixed-length format records (F or FA) or undefined-format records (U or UA), blksize is the same as lrecl.
  • If recfm specifies unblocked variable-length format records (V or VA), blksize is lrecl plus 4.
  • If recfm specifies blocked records (FB, FBA, FBS, FBSA, VB, or VBA) for a DASD device on z/OS, Language Environment uses a blksize of 0 so the system can determine the optimum blksize.
  • If recfm specifies blocked fixed-length format records (FB, FBA, FBS, or FBSA) for a terminal , blksize is the same as lrecl.
  • If recfm specifies blocked variable-length format records (VB or VBA) for a terminal, blksize is lrecl plus 4.
  • For all other cases, blksize is calculated to provide the largest number of records per block, up to 100 records per block, that does not exceed the maximum blksize of 32760.
• Language Environment does not diagnose combinations of recfm, lrecl, and blksize that are not valid but the system can detect an error condition on the first attempt to write to the message file.
• Language Environment does not check the validity of the MSGFILE ddname. A ddname that is not valid generates an error condition on the first attempt to write to the message file.
• C/C++ consideration—C output directed to stderr and perror() messages go to the MSGFILE destination.
• PL/I consideration—runtime messages in PL/I programs are directed to the message file instead of to the PL/I SYSPRINT STREAM PRINT file.

  User-specified output is directed to the PL/I SYSPRINT STREAM PRINT file. To direct this output to the message file, specify MSGFILE(SYSPRINT).

  Use of MSGFILE(SYSPRINT) restricts the LINESIZE for PL/I programs to a maximum of 255.

• Fortran consideration—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 Fortran runtime Migration Guide.
• 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).

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 CEEMSG—Get, format, and dispatch a message and CEEMOUT—Dispatch a message.
• 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 examples of getting and formatting messages, including HLL runtime output, see CEEMSG—Get, format, and dispatch a message.
• For more information about perror() and stderr see the 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.