.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "QMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" qmsg 
.SH NAME
qmsg \- send message to batch jobs
.SH SYNOPSIS
.LP
\fBqmsg\fP \fB[\fP\fB-E\fP\fB][\fP\fB-O\fP\fB]\fP \fImessage_string
job_identifier\fP \fB...
\fP
.SH DESCRIPTION
.LP
To send a message to a batch job is to request that a server write
a message string into one or more output files of the batch
job. A message is sent to a batch job by a request to the batch server
that manages the batch job. The \fIqmsg\fP utility is a
user-accessible batch client that requests the sending of messages
to one or more batch jobs.
.LP
The \fIqmsg\fP utility shall write messages into the files of batch
jobs by sending a \fIJob Message Request\fP to the batch
server that manages the batch job. The \fIqmsg\fP utility shall not
directly write the message into the files of the batch
job.
.LP
The \fIqmsg\fP utility shall send a \fIJob Message Request\fP for
those batch jobs, and only those batch jobs, for which a
batch \fIjob_identifier\fP is presented to the utility.
.LP
The \fIqmsg\fP utility shall send \fIJob Message Request\fPs for batch
jobs in the order in which their batch
\fIjob_identifier\fPs are presented to the utility.
.LP
If the \fIqmsg\fP utility fails to process any batch \fIjob_identifier\fP
successfully, the utility shall proceed to process
the remaining batch \fIjob_identifier\fPs, if any.
.LP
The \fIqmsg\fP utility shall not exit before a \fIJob Message Request\fP
has been sent to the server that manages the batch
job that corresponds to each successfully processed batch \fIjob_identifier\fP.
.SH OPTIONS
.LP
The \fIqmsg\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported by the implementation:
.TP 7
\fB-E\fP
Specify that the message is written to the standard error of each
batch job. 
.LP
The \fIqmsg\fP utility shall write the message into the standard error
of the batch job.
.TP 7
\fB-O\fP
Specify that the message is written to the standard output of each
batch job. 
.LP
The \fIqmsg\fP utility shall write the message into the standard output
of the batch job.
.sp
.LP
If neither the \fB-O\fP nor the \fB-E\fP option is presented to the
\fIqmsg\fP utility, the utility shall write the message
into an implementation-defined file. The conformance document for
the implementation shall describe the name and location of the
implementation-defined file. If both the \fB-O\fP and the \fB-E\fP
options are presented to the \fIqmsg\fP utility, then the
utility shall write the messages to both standard output and standard
error.
.SH OPERANDS
.LP
The \fIqmsg\fP utility shall accept a minimum of two operands, \fImessage_string\fP
and one or more batch
\fIjob_identifier\fPs.
.LP
The \fImessage_string\fP operand shall be the string to be written
to one or more output files of the batch job followed by a
<newline>. If the string contains <blank>s, then the application shall
ensure that the string is quoted. The
\fImessage_string\fP shall be encoded in the portable character set
(see the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character Set).
.LP
All remaining operands are batch \fIjob_identifier\fPs that conform
to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP
).
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
None.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIqmsg\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
Determine the locale for the interpretation of sequences of bytes
of text data as characters (for example, single-byte as
opposed to multi-byte characters in arguments).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fILOGNAME\fP
Determine the login name of the user.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
None.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
In addition to the default behavior, the \fIqmsg\fP utility shall
not be required to write a diagnostic message to standard
error when the error reply received from a batch server indicates
that the batch \fIjob_identifier\fP does not exist on the
server. Whether or not the \fIqmsg\fP utility waits to output the
diagnostic message while attempting to locate the job on other
servers is implementation-defined.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
None.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
The \fIqmsg\fP utility allows users to write messages into the output
files of running jobs. Users, including operators and
administrators, have a number of occasions when they want to place
messages in the output files of a batch job. For example, if a
disk that is being used by a batch job is showing errors, the operator
might note this in the standard error stream of the batch
job.
.LP
The options of the \fIqmsg\fP utility provide users with the means
of placing the message in the output stream of their choice.
The default output stream for the message-if the user does not designate
an output stream-is implementation-defined, since many
implementations will provide, as an extension to this volume of IEEE\ Std\ 1003.1-2001,
a log file that shows the history
of utility execution.
.LP
If users wish to send a message to a set of jobs that meet a selection
criteria, the \fIqselect\fP utility can be used to acquire the appropriate
list of job identifiers.
.LP
The \fB-E\fP option allows users to place the message in the standard
error stream of the batch job.
.LP
The \fB-O\fP option allows users to place the message in the standard
output stream of the batch job.
.LP
Historically, the \fIqmsg\fP utility is an existing practice in the
offerings of one or more implementors of an NQS-derived
batch system. The utility has been found to be useful enough that
it deserves to be included in this volume of
IEEE\ Std\ 1003.1-2001.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIBatch Environment Services\fP , \fIqselect\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .