__console2() — Enhanced console communication services

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.

__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:

1. 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.
2. 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.

__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.

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.

⁄* 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;
}