Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
| z/OS® UNIX |
both |
|
Format
#include <sys/__messag.h>
int __console(struct __cons_msg *cons, char *modstr, int *concmd);
General description
The __console() function
is used to communicate with the operator's console. The __console()
function allows users to send messages to the operator's console and
to wait on a modify/stop request from the console.
The parameters
supported are:
- cons
- If the argument is not NULL, it points to a structure specifying
the message that is to be sent to the operator's console. If the
argument is NULL then no message is sent.
- modstr
- Specifies the string where __console() returns the data entered
at the operator's console. If modstr is not NULL the invoker will
wait until an operator MODIFY's the invoking job and specifies 'APPL='
parameter. The length of modstr should be 128-byte. See z/OS MVS System Commands for
more information on the MODIFY console command. If the argument is
NULL then the __console() function will not wait on operator console
commands.
- concmd
- If a console command was issued against the invoking job, the
__console() function will set the command type. Valid types are, _CC_modify
(function received a modify request) and _CC_stop (function received
a stop request).
The cons structure is defined in the <sys/__messag.h>
header and has the following format.
struct __cons_msg {
short __reserved0;
char __reserved1[2];
union {
struct {
int __msg_length;
char *__msg;
char __reserved2[8];
} __f1;
} __format;
};
- __reserved0
- Reserved for future use.
- __reserved1[2]
- Reserved for future use.
- __format.__f1.__msg_length
- Length of message, not including the NULL terminator.
- __format.__f1.__msg
- A character string containing the message to be sent to the operator
console.
- __format.__f1.__reserved2[8]
- Reserved for future use.
Note: The length of the message must be between
1 and 17850 characters for invokers with appropriate privileges, and
between 1 and 17780 for invokers without appropriate privileges. The
number of lines written to the console is limited to 255. In the case
of an unprivileged user, one of those lines is used for the message
ID and the invoker's login name. If the message length is exceeded,
no lines are written and the service returns an EINVAL. If the number
of lines is exceeded, the service returns an EINVAL, but the first
255 lines are written to the console.
Returned value
If successful, __console()
returns 0.
If unsuccessful, __console() returns -1 and sets
errno to one of the following values:
- Error Code
- Description
- EFAULT
- One of the following errors was detected:
- All or part of the cons structure is not addressable by the caller.
- All or part of the modstr string is not addressable by the caller.
- EINTR
- __console() was interrupted by a signal.
- EINVAL
- The cons structure contains errors.
- EMVSERR
- z/OS environmental
or internal error has occurred.
Example
CELEBC41
⁄* CELEBC41
This example prints a simple message to the console using the
__console() function.
*⁄
#include <sys⁄__messag.h>
#include <errno.h>
#include <string.h>
#include <stdio.h>
int main(int argc, char** argv) {
struct __cons_msg cmsg;
char buf[256] = "A message on the console";
int rc;
int cmsg_cmd = 0;
⁄* fill in the __cons_msg structure *⁄
cmsg.__format.__f1.__msg = buf;
cmsg.__format.__f1.__msg_length = strlen(buf);
rc = __console(&cmsg,NULL,&cmsg_cmd);
if(rc == -1) {
printf("__console() failed\n");
printf("%s\n",strerror(errno));
}
else {
printf("__console() successful. Check console for message.\n");
}
return 0;
}