The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### NAME

> qmsg - send message to batch jobs

#### SYNOPSIS

> ``[OB BE] qmsg` [`-EO`] message_string job_identifier`...``

#### DESCRIPTION

> 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 qmsg utility is a user-accessible batch client that requests the sending of messages to one or more batch jobs.

> The qmsg utility shall write messages into the files of batch jobs by sending a Job Message Request to the batch server that manages the batch job. The qmsg utility shall not directly write the message into the files of the batch job.

> The qmsg utility shall send a Job Message Request for those batch jobs, and only those batch jobs, for which a batch job_identifier is presented to the utility.

> The qmsg utility shall send Job Message Requests for batch jobs in the order in which their batch job_identifiers are presented to the utility.

> If the qmsg utility fails to process any batch job_identifier successfully, the utility shall proceed to process the remaining batch job_identifiers, if any.

> The qmsg utility shall not exit before a Job Message Request has been sent to the server that manages the batch job that corresponds to each successfully processed batch job_identifier.

#### OPTIONS

> The qmsg utility shall conform to XBD Utility Syntax Guidelines .

> The following options shall be supported by the implementation:

> -E
>   Specify that the message is written to the standard error of each batch job.

>   The qmsg utility shall write the message into the standard error of the batch job.

> -O
>   Specify that the message is written to the standard output of each batch job.

>   The qmsg utility shall write the message into the standard output of the batch job.

> If neither the -O nor the -E option is presented to the qmsg 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 -O and the -E options are presented to the qmsg utility, then the utility shall write the messages to both standard output and standard error.

#### OPERANDS

> The qmsg utility shall accept a minimum of two operands, message_string and one or more batch job_identifiers.

> The message_string 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> characters, then the application shall ensure that the string is quoted. The message_string shall be encoded in the portable character set (see XBD Portable Character Set).

> All remaining operands are batch job_identifiers that conform to the syntax for a batch job_identifier (see Batch Job Identifier).

#### STDIN

> Not used.

#### INPUT FILES

> None.

#### ENVIRONMENT VARIABLES

> The following environment variables shall affect the execution of qmsg:

> LANG
>   Provide a default value for the internationalization variables that are unset or null. (See XBD Internationalization Variables the precedence of internationalization variables used to determine the values of locale categories.)
> LC_ALL
>   If set to a non-empty string value, override the values of all the other internationalization variables.
> LC_CTYPE
>   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).
> LC_MESSAGES
>   Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
> LOGNAME
>   Determine the login name of the user.

#### ASYNCHRONOUS EVENTS

> Default.

#### STDOUT

> None.

#### STDERR

> The standard error shall be used only for diagnostic messages.

#### OUTPUT FILES

> None.

#### EXTENDED DESCRIPTION

> None.

#### EXIT STATUS

> The following exit values shall be returned:

> 0
>   Successful completion.
> >0
>   An error occurred.

#### CONSEQUENCES OF ERRORS

> In addition to the default behavior, the qmsg 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 job_identifier does not exist on the server. Whether or not the qmsg utility waits to output the diagnostic message while attempting to locate the job on other servers is implementation-defined.

The following sections are informative.

#### APPLICATION USAGE

> None.

#### EXAMPLES

> None.

#### RATIONALE

> The qmsg 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.

> The options of the qmsg 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 POSIX.1-2008, a log file that shows the history of utility execution.

> If users wish to send a message to a set of jobs that meet a selection criteria, the qselect utility can be used to acquire the appropriate list of job identifiers.

> The -E option allows users to place the message in the standard error stream of the batch job.

> The -O option allows users to place the message in the standard output stream of the batch job.

> Historically, the qmsg 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 POSIX.1-2008.

#### FUTURE DIRECTIONS

> The qmsg utility may be removed in a future version.

#### SEE ALSO

> Batch Environment Services, qselect

> XBD Portable Character Set, Environment Variables, Utility Syntax Guidelines

#### CHANGE HISTORY

> Derived from IEEE Std 1003.2d-1994.

#### Issue 6

> The LC_TIME and TZ entries are removed from the ENVIRONMENT VARIABLES section.

#### Issue 7

> The qmsg utility is marked obsolescent.

> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]