__console() (BPX1CCS, BPX4CCS) — Communicate with console (modify/stop/WTO/DOM)

Function

The __console() service sends messages to the console and waits on a modify/stop request from the console. Additional functions available under __console2() allow you to specify routing and descriptor codes for messages sent to the console and delete held messages from the console, using message IDs or tokens. These functions are activated under the expanded BPXYCCA structure in the Version 2 section. See the usage notes for information about using the __console2() functions. Additionally, the BPXYCCA structure Version 3 section provides the ability to specify a user-supplied CART and console ID. This function can be used by applications that communicate with more than one console to ensure that the messages go to the expected console.

Requirements

Parameters

MsgAttributes_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the area that contains the message attributes of the message that is to be sent to the console. If the length is zero, the MsgAttributes parameter is ignored, and no message is sent to the console.

MsgAttributes

Supplied parameter

Type:

Structure

Length:

Specified by the MsgAttributes_length parameter.

The name of the area that contains the message attributes of the message that is to be sent to the console. Included in this macro mapping are the address and length of the message to be sent. The area is mapped by BPXYCCA. For information about the content of this area, see BPXYCCA — Map input/output structure for __console().

Modify_buffer_ptr

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

A fullword (doubleword) field that contains the 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-aligned. The length of the string copied is returned in the Modify_string_length parameter. The data returned is folded to uppercase. If this parameter is zero, this service does not wait for or process any console modify/stop commands.

Modify_string_length

Returned parameter

Type:

Integer

Character set:

No restriction

Length:

Fullword

The name of a fullword in which the __console() service returns the length of the modify string that is returned at the location specified by Modify_buffer_ptr. If the Modify_buffer_ptr is zero, this parameter is unchanged.

Console_command

Returned parameter

Type:

Integer

Character set:

No restriction

Length:

Fullword

The name of a fullword in which the __console() service returns the type of command that was issued. The values are CONSOLE_MODIFY and CONSOLE_STOP.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the __console() service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the __console() service stores the return code. The __console() service returns Return_code only if Return_value is 0. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The __console() service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	A message attribute was not valid. An error was detected in one of the fields described by BPXYCCA (JrMsgLength, JRMsgMaxLines, or JrMsgAttrErr).
EINTR	The syscall was interrupted by a signal.
EFAULT	User storage that was passed in could not be accessed. The reason code identifies the bad user storage (JRMsgIdList, JrDescList, JrRoutingList, and JrMsgId).
EPERM	The specified routing code requires the user to have superuser authority (JrAuthRoutingCode).

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the __console() service stores the reason code. The __console() service returns Reason_code only if Return_value is 0. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. Only one thread per address space is allowed to wait on console commands. If the Modify_buffer_ptr is nonzero, there can be no other instance of the __console() service waiting for console input. This restriction applies to both the multithread and the multiprocess models. Subsequent attempts fail with an EMVSERR and JrNoMulti.
2. Messages sent to the console go to the last console that issued a modify command to this job. If no modify has been issued to this job, the message goes to the console that started this job. If this job was not started (that is, invoker created by the fork service), the message goes to the default console route code.

   Routing codes specified in the message attribute area override the current message routing.

3. An invoker is deemed to have appropriate privileges for this service if the BPX.CONSOLE resource in the FACILITY class is defined and the invoker is permitted to that resource, or if the invoker is running with an effective UID of 0.
4. If the invoker does not have appropriate privileges (see Authorization), a message ID (BPXM023I) and the invoker's login name are prefixed to the specified message text. If the invoker has appropriate privileges, the invoker is responsible for its own message headers. Any message sent to the console should comply with MVS™ message guidelines. See z/OS MVS System Messages, Vol 3 (ASB-BPX) for more information about how to prefix messages with the correct message header. These guidelines are not enforced by this service.
5. 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.
6. The __console() service provides limited formatting in that it recognizes the NEWLINE character and attempts to break on word boundaries. If a blank is found within the last 10 characters of the line, the __console() service breaks the line there. If no blanks are found within the last 10 characters, the line break occurs after the 70th character.
7. Use of QEDIT and console service control blocks to listen to console commands, in combination with this service, may result in failures of EMVSERR JrUnexpectedErr.
8. Although the modify string buffer is 128 bytes, the maximum modify string that can be received from the console is less. The largest string that can be typed in from the console is 126 bytes, and this must include the modify command, job name, and APPL= parameters. For example, F SERVER01,APPL= consumes 16 characters of the 126-character string.
9. If the modify_buffer_ptr is specified, the invoking thread waits until either a modify command is issued to this thread's job, or a caught or terminating signal is generated to this thread. The __console() service is also an interrupt point for pthread_cancel.
10. If the console operator enters nothing after the APPL=, the Modify_buffer is unchanged and a Modify_string_length of zero is returned.
11. If the Console_command type returned is CONSOLE_STOP, the Modify_string_length is set to zero. Console stop commands do not pass string data. It is up to the application to handle the stop command; the system takes no action against the process in response to a stop command. The application may choose to ignore the stop command, or terminate the process through services such as BPX1EXI (BPX4EXI).
12. To use the functions available under console2(), specify the new version (CCA_#Ver02) and the correct length (CCA#Ver2Len) in the CCA when invoking the __console() service.
13. The three __console() operations (WTO, DOM, and WAIT) can be performed in a single request. The order of operations is WTO (issue messages), DOM (delete messages), and WAIT (for a MODIFY or STOP command).

Characteristics and restrictions

There are no restrictions on the use of the __console() service.