__console2() — Enhanced console communication services
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
z/OS® UNIX | both | OS/390® V2R10 |
Format
#include <sys/__messag.h>
int __console2(struct __cons_msg2 *cons, char *modstr, int *concmd);
General description
The __console2() function is used to communicate with the operator console. The __console2() function allows users to send messages to the operator console with the ability to specify routing codes and message descriptor codes, wait on a modify or stop request from the console, and to delete messages from operator console using either a message ID or token.
The
__console2() function parameters are as follows:
- cons
- Specifies the address of the structure containing the console communication information. The mapping of the structure is provided below. If this parameter is NULL, then no message is sent to the operator console and no messages are deleted from the console.
- modstr
- Address of a 128-byte buffer that is to be used to receive a string
of EBCDIC data from the console MODIFY command. All characters that
appear to the right of the
APPL=
are placed into this buffer, left justified. The data returned is folded to uppercase. If this parameter is NULL, then the __console2() function does not wait on operator console commands. - concmd
- Address of a 32-bit integer where the __console2() function returns
the type of command that was issued on the console. If this parameter
is set to NULL, the __console2() function will fail with EFAULT. The
command types are:
- _CC_modify
- Function received a modify request.
- _CC_stop
- Function received a stop request.
The console communication information is specified
in a structure pointed to by the cons parameter. The structure
contains the following fields:
- __cm2_format
- Specifies the format of the structure. This field must be set
to one of the following:
- __CONSOLE_FORMAT_2
- Used to indicate structure format 2.
- __CONSOLE_FORMAT_3
- Used to indicate structure format 3.
- __cm2_msglength
- The length of the message to be written to the console. A value
of zero indicates that no message is to be sent to the operator console.
Notes:
- The length of the message must be between 1 and 17850 characters for authorized users, and between 1 and 17780 for unauthorized users. The number of lines written to the console is limited to 255. In the case of an unauthorized user, one of those lines is used for the message ID and the user ID of the user. If the message length is exceeded, no lines are written and the service returns an EINVAL error code. If the number of lines is exceeded, the service returns an EINVAL error code, but the first 255 lines are written to the console.
- An authorized user is one with appropriate privileges, as described in the
Authorization
topic in z/OS UNIX System Services Programming: Assembler Callable Services Reference.
- __cm2_msg
- Pointer to a NULL terminated string containing the message to be written to the console. A value of NULL indicates no message is to be sent to the operator console.
- __cm2_routcde
- Pointer to an unsigned integer array containing the routing codes to be assigned to the message.
The array is terminated by a zero value. Allowable routing codes are 1 to 128 for authorized users,
and 1 to 28 for unauthorized users. For more information on routing codes, see z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO.
Note: An authorized user is one with appropriate privileges, as described in the
Authorization
topic in z/OS UNIX System Services Programming: Assembler Callable Services Reference. - __cm2_descr
- Pointer to an unsigned integer array containing the message descriptor codes to be assigned to the message. The array is terminated by a zero value. Allowable descriptor codes are 1 to 13. Descriptor codes 1 through 6, 11, and 12 are mutually exclusive. Codes 7 through 10, and 13 can be assigned in combination with any other code. For more information on descriptor codes, see z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO.
- __cm2_mcsflag
- Specifies one or more of the following flags:
- __CONSOLE_HRDCPY
- Queue the message for hard copy only. The message will not be displayed on the console.
- __cm2_token
- Specifies a 4-byte token to be associated with this message. This field is used to identify a group of messages which can be deleted using the DOM feature of the __console2() function. The token must be unique within an address space and can be any value. A token value of zero indicates no token is specified and the message issued will not be associated with any token.
- __cm2_msgid
- An unsigned 32-bit integer field where the __console2() function
will place the message ID associated with the message last sent to
the console. This message ID can be used to delete a message when
it is no longer needed by specifying it using the DOM feature of the
__console2() function. A value of NULL indicates that the message
ID is not to be returned. Note: The value returned in __cm2_msgid is an internal message identifier associated with the message written to the console. The value is not text and it should not be confused with any textual part of a message that might otherwise be considered a message ID.
- __cm2_dom_token
- Specifies a 4-byte token which represents a message or group of messages to be deleted from the console. All messages previously issued with this token will be deleted from the console. This field is mutually exclusive with __cm2_dom_msgid. A value of zero indicates that no token is specified.
- __cm2_dom_msgid
- Pointer to an unsigned integer array containing message IDs to be deleted from the console. A maximum of 60 message IDs can be in the array. The array is terminated by a zero value. The array terminator is not part of the 60 message IDs. This field is mutually exclusive with __cm2_dom_token. A value of NULL indicates that no message IDs are specified.
The
console communication information structure includes the following
additional fields when using the __CONSOLE_FORMAT_3 format. These
fields are not available when using the __CONSOLE_FORMAT_2 format.
- __cm2_mod_cartptr
- Pointer to the 8-byte command and response token (CART) returned by a MODIFY or STOP command.
- __cm2_mod_considptr
- Pointer to the 4-byte console ID returned by a MODIFY or STOP command.
- __cm2_msg_cart
- Specifies an 8-byte CART to be used on WTO when the message is issued.
- __cm2_msg_consid
- Specifies a 4-byte console ID to be used on WTO when the message is issued.
Note: All operations can be done in a single request.
The order of operation is to issue messages, delete messages, and
then wait for a MODIFY or STOP command.
Returned value
If successful, __console2() returns 0.
If unsuccessful, __console2() returns -1 and sets
ERRNO to one of the following values:
- Error Code
- Description
- EFAULT
- The __console2() function was unable to address all or part of
the cons structure, all of part of the routing codes array,
all or part of the descriptor codes array, all or part of the array
of DOM message IDs, all or part of the modstr, or the concmd parameter
was NULL.
Another possible cause is that __cm2_msgid points to storage which is not accessible.
- EINTR
- The __console2() function was interrupted by a signal.
- EINVAL
- The structure pointed to by cons contains errors.
For example, mutually exclusive parameters were specified, a non-valid routing code was specified, a non-valid descriptor code or mutually exclusive descriptor codes were specified, or there were more than 60 entries in the array of DOM message IDs.
- EMVSERR
- A z/OS environmental or internal error has occurred. Use the __errno2() function to obtain diagnostic information that will help determine the cause of the problem.
- EPERM
- An unauthorized user specified a routing code in the range 29 through 128. Only authorized (superuser) users (UID=0) can specify routing codes in that range.
Example
CELEBC42
/* CELEBC42
This example prints a simple message to the console using the
__console2() function. A routing and descriptor code are also
assigned to the message.
*/
#include <sys/__messag.h>
#include <errno.h>
#include <string.h>
#include <stdio.h>
int main(int argc, char** argv) {
struct __cons_msg2 cmsg;
char buf[256] = "A message on the console";
int rc;
int cmsg_cmd;
unsigned int cmsg_rout[2] = {1,0};
unsigned int cmsg_desc[2] = {12,0};
/* Fill in the __cons_msg2 struct */
cmsg.__cm2_format = __CONSOLE_FORMAT_2;
cmsg.__cm2_msg = buf;
cmsg.__cm2_msglength = strlen(buf);
cmsg.__cm2_routcde = cmsg_rout;
cmsg.__cm2_descr = cmsg_desc;
cmsg.__cm2_token = 0;
cmsg.__cm2_msgid = NULL;
cmsg.__cm2_dom_token = 0;
rc = __console2(&cmsg,NULL,&cmsg_cmd);
if(rc == -1) {
printf("__console2() failed\n");
printf("%s\n",strerror(errno));
}
else {
printf("__console2() successful. Check console for message\n");
}
return 0;
}