Executes an API command in an existing (stateful) or new transient (stateless) session.
Returns items as requested by the query parameters. An existing session is used when a valid cookie is used as an argument on the --cookie option. This is the preferred scenario when multiple transactions are expected since it provides significant performance benefits. It requires server affinity for sessions in a clustered server environment.
A new transient session will be created if a --authorization or --user option is provided and a --cookie option is not. A transient session exists only for the current transaction and meets the goal of statelessness as defined by ROA and REST. However, it is much less efficient than using an existing session across multiple transactions, and does not preserve the state of the underlying (E)JES API. Nevertheless, it is the prefered scenario where a single transaction and statelessness suffice.
See the (E)JES REST API swagger documentation for details on the mapped options. Enclose all option arguments in double quotes if they include spaces, semicolons, or symbols that are reserved in your terminal shell or if they might otherwise be ambiguous to the shell. Options flagged with "initParms model" are valid only for stateless transactions on the exec command.
For a command group overview, issue: zowe ejes api -h
Usage
zowe ejes api exec [options]
Query Item Options
-
--authorization (string)
- If you do not specify the --cookie option, you must include --user and --password or this option. The base64 encoded authentication string can be of the form userid:password or userid:group:password. If supplied, it overrides the profile user and password settings and starts a new session.
-
--cookie (string)
-
Supply the cookie output by a stateful request. This option supports optional syntax to enable automatic managment of the cookie without scraping from stdout.
--cookie [<cookie-value>|read[<pin>]|write[<pin>]
The CLI can manage a stateful cookie transaction proactively. On the init, specify --cookie write or --cookie write-pin where pin can be any alphanumeric string. On the exec, cancel-download, and term specify --cookie read or --cookie read-pin. The cookie generated by the host is managed in the user's work directory. A pin is required only when there are multiple simultaneous sessions.
-
-c (string)
-
A list of comma separated, case-insensitive names of columns to include in the response. If omitted, all columns for the current tabular display are included.
This parameter only applies to enumerated data containing columns, specifically, the columns and rows items of the q parameter.
Limiting the included columns to only those you need can dramatically improve the resonse time of the request and significantly reduce system resources.
-
-q (string)
-
A list of comma separated, case-insensitive items to include in the response. If omitted, no items are included.
Limiting the included items to only those you need can improve response time.
The following items are supported: columns, environment, execParms, find, function, initParms, jobs, keys, lines, loginfo, rows, lineCommands, message, notice, platformEncoding, position, screen, submittedJobs, userLog, and version. These represent the response properties as described in the models section of this help. The value all can be used to include all of the above items, but generally you should only request the items you need.
-
-d (string)
-
A download type, either pdf or text.
When specified, all other query parameters are ignored. The Content-Type response header will report either application/pdf or text/plain (charset utf-8) if no error occurred, and application/json if an error occurred. If no error occurred, a Content-Disposition response header will supply a suggested filename.
A pdf or text property may be included in the POST data to override default pdf and text formatting options.
This parameter provides pdf or text data in the output stream and does not require enumeration.
The API must be positioned on a browser type display to download data. Afterwards, the positioning may have changed depending on the amount specified.
You can use CancelDownload to cancel a long running download.
-
-m (string)
-
A mail attachment type, either pdf or text.
At a minimum, a mail property is required in the POST data to specify one or more recipients. A pdf or text property may also be included to override default pdf and text formatting options.
The API must be positioned on a browser type display to send a mail attachment. Afterwards, the positioning may have changed depending on the amount specified.
Note that you cannot use CancelDownload to cancel a long running mail attachement request because the response
containing the needed Cookie is not sent until after mail has been sent.
Init Request Options
-
--casKey (string)
- See the initParms model in the Swagger documentation.
-
--columns (string)
- See the initParms model in the Swagger documentation.
-
--extractdd (string)
- See the initParms model in the Swagger documentation.
-
--ipaddress (string)
- See the initParms model in the Swagger documentation.
-
--luName (string)
- See the initParms model in the Swagger documentation.
-
--patterndd (string)
- See the initParms model in the Swagger documentation.
-
--rows (string)
- See the initParms model in the Swagger documentation.
-
--subsystem (string)
-
--useragent (string)
- See the initParms model in the Swagger documentation.
Exec Request Options
-
--command (string)
- See the execParms model in the Swagger documentation.
-
--commanddata (string)
- See the execParms model in the Swagger documentation. Insert "\n" in the string to indicate line breaks.
-
--commanddatafile (string)
- The contents of this file (usually JCL on the local workstation file system) must be escaped properly for --commanddata. See the execParms model in the Swagger documentation. Uses EJES_SUBMIT_PATH for the path if it exists in the environment.
-
--enumtime (number)
- See the execParms model in the Swagger documentation.
-
--enumvalue (number)
- See the execParms model in the Swagger documentation.
-
--showhiddencolumns (boolean)
- See the execParms model in the Swagger documentation.
-
--translatescreen (boolean)
- See the execParms model in the Swagger documentation.
-
--waitforresponse (boolean)
- See the execParms model in the Swagger documentation.
PDF and TEXT Common Options
-
--amount (number)
- See the pdf or text model in the Swagger documentation.
-
--blockid (number)
- See the pdf or text model in the Swagger documentation.
-
--cc (string)
- See the pdf or text model in the Swagger documentation. (Carriage-control)
-
--count (number)
- See the pdf or text model in the Swagger documentation.
-
--recordid (number)
- See the pdf or text model in the Swagger documentation.
-
--start (number)
- See the pdf or text model in the Swagger documentation.
-
--todend (number)
- See the pdf or text model in the Swagger documentation.
-
--todstart (number)
- See the pdf or text model in the Swagger documentation.
PDF Download Options
-
--decorate (string)
- See the pdf model in the Swagger documentation.
-
--font (string)
- See the pdf model in the Swagger documentation.
-
--orientation (string)
- See the pdf model in the Swagger documentation.
-
--overflow (string)
- See the pdf model in the Swagger documentation.
-
--pagesize (string)
- See the pdf model in the Swagger documentation.
PDF Security Property Options
-
--allowassembly (boolean)
- See the pdf model in the Swagger documentation.
-
--allowcopying (boolean)
- See the pdf model in the Swagger documentation.
-
--allowmodification (boolean)
- See the pdf model in the Swagger documentation.
-
--allowprinting (boolean)
- See the pdf model in the Swagger documentation.
-
--masterpassword (string)
- See the pdf model in the Swagger documentation.
-
--openpassword (string)
- See the pdf model in the Swagger documentation.
Mail Options
-
--bcc (string)
- See the mail model in the Swagger documentation.
-
--body (string)
- See the mail model in the Swagger documentation. Insert "\n" in the string to indicate line breaks.
-
--bodyfile (string)
- See the mail model in the Swagger documentation. The contents of the file are read and escaped properly for --body. Uses EJES_SUBMIT_PATH for the path if it exists in the environment.
-
--carboncopy (string)
- See the cc property the mail model in the Swagger documentation.
-
--from (string)
- See the mail model in the Swagger documentation.
-
--html (string)
- See the mail model in the Swagger documentation.
-
--subject (string)
- See the mail model in the Swagger documentation.
-
--to (string)
- See the mail model in the Swagger documentation.
Platform-encoding Options
Debug Visualization Options
EJES Connection Options
-
--protocol | --prot (string)
-
Protocol used to access (E)JES server.
Default value: https
Allowed values: http, https, list, help
-
--host (string)
- The (E)JES server host name.
-
--port (number)
-
The (E)JES server port.
Default value: 443
-
--user (string)
- Mainframe (E)JES user name, which can be the same as your TSO login.
-
--password | --pass | --pw (string)
- Mainframe (E)JES password, which can be the same as your TSO password.
-
--reject-unauthorized | --rejectunauthorized | --ru (boolean)
-
--base-path | --basepath | --bp (string)
- The base path for your API mediation layer instance. Specify this option to prepend the base path to all (E)JES resources when making REST requests.
-
--color-scheme | --scheme | --cs (string)
-
Accessibility option: Specify the name of a color scheme. User scheme files may also be created and specified to provide better contrast or to favor easier to see colors. For a how-to, use "zowe ejes emulate batch --helpApp scheme-info". Zowe ejes log stream ignores this option as it outputs plain text by default, only colorizing when ANSI color options are specified.
Allowed values: dark, light, powershell, nono, none, user-scheme-file, list, help
Default value: dark
-
--no-color | --nocolor | --nc (string)
- Accessibility option: Specify to prevent colorization of the CLI. Same effect as defining NO_COLOR or FORCE_COLOR=0.
Profile Options
Examples
- Perform a stateless transaction that submits a job using the --command option. It shows the status of jobs with the same name, sorting so the most recent is shown first. The --enumvalue option is requesting the top 5 lines. The query parameter -q is requesting the message array that will contain the submit result, lines of output, and the array of jobs submitted in this session. The --commanddata option supplies the JCL to submit referred to by the "api-array". The "\n" are line separators an editor would supply.
Example:
* `$ zowe ejes api exec --command "submit api-array;st iefbr14;sort time d;upd" --enumvalue 5 -q message,lines,submittedJobs --rfj --commanddata "//IEFBR14 JOB IEFBR14,'IEFBR14',CLASS=A,MSGCLASS=H\n//EXEC EXEC PGM=IEFBR14\n//"`
- Perform the same stateless transaction above but use the --commanddatafile option to read a file from the workstation. If EJES_SUBMIT_PATH is defined in the environment, that will be used as the file path, otherwise the same directory the CLI is run in will be used if a full path is not supplied.
Example:
* `$ zowe ejes api exec --command "submit api-array;st iefbr14;sort time d;upd" --enumvalue 5 -q message,lines,submittedJobs --rfj --commanddatafile "iefbr14.jcl"`
- Perform a stateful request. In this case, a previous request positioned the (E)JES api in a job browser. This example downloads the file as PDF using the -d option. It causes the carriage control symbols to be interpretted with the --cc option. Then specifies stateful session with the cookie it generated specified on the --cookie option. The sysout is download to a file with the name consistent with the browsed data set or browser. If EJES_DOWNLOAD_PATH exists in the environment, the path is used for the download. Otherwise, the file is created in the current working directory. (For managed cookie stateful request examples, issue: Zowe ejes api -h)
Example:
* `$ zowe ejes api exec -d text --cc interpret --cookie "EJESWEB_54761=B6910D...;path=/EjesWeb;Secure;HttpOnly"`