z/OS console services
The z/OS console services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. The z/OS console services provide a programming interface for performing z/OS® console operations.
With the z/OS console services, you can issue system commands and work with both solicited messages (messages that were issued in response to the command) and unsolicited messages (other messages that might or might not have been issued in response to the command). z/OS console services establish an extended MCS (EMCS) console, which is then used to issue commands and receive messages.
| Operation | HTTP method and URI path |
|---|---|
| Issue a command | |
| Get a command response | |
| Get the detect result for unsolicited messages | |
Required authorizations
Your user ID must have the same authority when issuing a command with the z/OS console services as when issuing a command through a console on a z/OS system.
- READ access to the MVS.MCSOPER.consolename resource in the OPERCMDS class, where consolename is the name of the EMCS console that is used to issue the command
- READ access to the CONSOLE resource in the TSOAUTH class.
- READ access to resource account in class ACCTNUM, where account is the value specified in the COMMON_TSO ACCT option in parmlib
- READ access to resource CEA.CEATSO.TSOREQUEST in class SERVAUTH
- READ access to resource proc in class TSOPROC, where proc is the value specified with the COMMON_TSO PROC option in parmlib.
The TSO/E address space services authority might already be defined if you are using z/OS data set and file REST services, as those services require similar authority.
Configuration
z/OS console services use the TSO CONSOLE command to establish an EMCS console, which allows you to issue system commands and retrieve the messages that are issued in response. Console attributes such as ROUTCODE and AUTH affect the messages that the EMCS console can receive and the commands that the console can issue. When you use the z/OS console services, be sure that the EMCS console that is established has the desired attributes. For information, see EMCS consoles in z/OS MVS Planning: Operations.
In addition, be aware that messages can be suppressed due to settings in the active MPFLSTxx member of parmlib. If a message associated with a command response is suppressed, a REST API call that attempts to detect that message will fail.
You can use SAF to control console attributes. The RACF ADDUSER command with the OPERPARM parameter sets console attributes when a user establishes an EMCS console. Using the ADDUSER command to control console attributes requires that you know in advance the name of the EMCS console that the z/OS Console service will use. The console name will be either a name that you specify on the Issue Command service, or a name that the service generates, as described in Issue a command.
ADDUSER CJOEYCN OPERPARM(AUTH(MASTER) ROUTCODE(ALL))To control the parameters that z/OS console services use when creating a TSO address space as the host for an EMCS console, use parmlib option COMMON_TSO ACCT(IZUACCT) REGION(50000) PROC(IZUFPROC). Configure this setting before z/OS console services are to be used. Otherwise, default values are used with z/OS console services.
Error handling
For errors that occur during the processing of a request, the API returns an appropriate HTTP status code to the calling client. An error is indicated by a 4nn code or a 5nn code. The HTTP status codes are described in the topics for the individual services.
In addition, a JSON object describes the error.
Error logging
Errors from the z/OS console services are logged in the z/OSMF log. You can use this information to diagnose the problem or provide it to IBM® Support, if required.
For information about working with z/OSMF log files, see IBM z/OS Management Facility Configuration Guide.
