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.

Table 1 lists the operations that the z/OS console services provide.
Table 1. Operations provided through the z/OS console services.
Operation HTTP method and URI path
Issue a command from a system console 
PUT /zosmf/restconsoles/consoles/consolename
PUT /zosmf/restconsoles/consoles/defcn
Get a command response 
GET /zosmf/restconsoles/consoles/console-name/solmsgs/Ckey-number
GET /zosmf/restconsoles/consoles/defcn/solmsgs/Ckey-number
Get the detect result for unsolicited messages 
GET /zosmf/restconsoles/consoles/consolename/detections/Dkey-number
GET /zosmf/restconsoles/consoles/defcn/detections/Dkey-number
Get messages from a hardcopy log 
GET /zosmf/restconsoles/v1/log

Using the Swagger interface

You can use the Swagger interface to display information about the z/OS console services REST APIs. For more information, see Using the Swagger interface.

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.

The required authority is:
  • 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 the <SAF_PREFIX>.*.izuUsers profile in the EJBROLE class. Or, at a minimum, READ access to the <SAF_PREFIX>.IzuManagementFacilityRestConsoles.izuUsers resource name in the EJBROLE class.
If you want to get messages from logs, the following is the required authority:
  • READ access to the SYSPLEX.OPERLOG resource in the LOGSTRM class
  • READ access to the <sysname>.+MASTER+.SYSLOG.*.* resource in the JESSPOOL class, where <sysname> is the name of the system on which the SYSLOG resides.
z/OS console services use z/OSMF TSO/E address space services to create a TSO address space as the host for an EMCS console. To use TSO/E address space services, you must have:
  • 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.

You must also ensure that the z/OSMF started task user ID, which is IZUSVR by default, has READ access to resource CEA.CEATSO.TSOREQUEST in class SERVAUTH.

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 Extended MCS 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.

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 z/OSMF log files in IBM z/OS Management Facility Configuration Guide.