Skip to content

Commit 2385f0b

Browse files
sebjulliandsebjulliand
authored
Merge pull request #62 from jenkinsci/runShellStep
Added `ibmiShellExec` step
2 parents 65f6b7d + 8e3fddc commit 2385f0b

File tree

9 files changed

+262
-114
lines changed

9 files changed

+262
-114
lines changed

‎README.md‎

Lines changed: 92 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -6,35 +6,35 @@ Jenkins plugin providing IBM i pipeline steps such as command execution, Db2 que
66
IFS transfers.
77

88
----
9-
109
- [Configuration](#configuration)
1110
- [Steps](#steps)
12-
- [onIBMi](#onibmi)
13-
- [ibmiCommand](#ibmicommand)
14-
- [ibmiRunSQL](#ibmirunsql)
15-
- [ibmiGetSAVF](#ibmigetsavf)
16-
- [ibmiPutSAVF](#ibmiputsavf)
17-
- [ibmiGetIFS](#ibmigetifs)
18-
- [ibmiPutIFS](#ibmiputifs)
19-
- [ibmiGetSPLF](#ibmigetsplf)
20-
- [ibmiWaitJob](#ibmiwaitjob)
11+
- [onIBMi](#onibmi)
12+
- [ibmiCommand](#ibmicommand)
13+
- [ibmiShellExec](#ibmishellexec)
14+
- [ibmiRunSQL](#ibmirunsql)
15+
- [ibmiGetSAVF](#ibmigetsavf)
16+
- [ibmiPutSAVF](#ibmiputsavf)
17+
- [ibmiGetIFS](#ibmigetifs)
18+
- [ibmiPutIFS](#ibmiputifs)
19+
- [ibmiGetSPLF](#ibmigetsplf)
20+
- [ibmiWaitJob](#ibmiwaitjob)
2121
- [Enumerations](#enumerations)
22-
- [OnMSGW](#onmsgw)
22+
- [OnMSGW](#onmsgw)
2323
- [Returned objects](#returned-objects)
24-
- [CallResult](#callresult)
25-
- [IBMiMessage](#ibmimessage)
26-
- [IBMiJob](#ibmijob)
27-
- [SQLResult](#sqlresult)
28-
- [SQLColumn](#sqlcolumn)
29-
- [SQLRow](#sqlrow)
30-
- [SaveFileContent](#savefilecontent)
31-
- [SAVFEntry](#savfentry)
32-
- [SpooledFiles](#spooledfiles)
33-
- [SpooledFile](#spooledfile)
24+
- [CallResult](#callresult)
25+
- [IBMiMessage](#ibmimessage)
26+
- [IBMiJob](#ibmijob)
27+
- [SQLResult](#sqlresult)
28+
- [SQLColumn](#sqlcolumn)
29+
- [SQLRow](#sqlrow)
30+
- [SaveFileContent](#savefilecontent)
31+
- [SAVFEntry](#savfentry)
32+
- [SpooledFiles](#spooledfiles)
33+
- [SpooledFile](#spooledfile)
3434
- [Examples](#examples)
35-
- [Save a library, download the Save File and archive its content description](#save-a-library-download-the-save-file-and-archive-its-content-description)
36-
- [Transfer a libray from one LPAR to another](#transfer-a-libray-from-one-lpar-to-another)
37-
- [Submit a job and download the spooled files it generated](#submit-a-job-and-download-the-spooled-files-it-generated)
35+
- [Save a library, download the Save File and archive its content description](#save-a-library-download-the-save-file-and-archive-its-content-description)
36+
- [Transfer a libray from one LPAR to another](#transfer-a-libray-from-one-lpar-to-another)
37+
- [Submit a job and download the spooled files it generated](#submit-a-job-and-download-the-spooled-files-it-generated)
3838

3939
## Configuration
4040

@@ -61,13 +61,13 @@ related resources are freed and the `IBMI_` environment variables are removed.
6161

6262
This steps loads the following environment variables during its execution. These variables are accessible through the
6363
`env` object (e.g. `env.IBMI_PROFILE`).
64-
| Name | Description |
64+
| Name | Description |
6565
|:-----------------|:-----------------------------------------------------------|
66-
| IBMI_HOST | The connected IBM i hostname |
67-
| IBMI_PROFILE | The user profile used to connect to the IBM i |
68-
| IBMI_CCSID | The current CCSID |
66+
| IBMI_HOST | The connected IBM i hostname |
67+
| IBMI_PROFILE | The user profile used to connect to the IBM i |
68+
| IBMI_CCSID | The current CCSID |
6969
| IBMI_COMMAND_JOB | The IBM i command job identifier (i.e. `number/user/name`) |
70-
| IBMI_VERSION | The OS version of the IBM i (i.e. `version.release`) |
70+
| IBMI_VERSION | The OS version of the IBM i (i.e. `version.release`) |
7171

7272
#### Parameters
7373

@@ -105,10 +105,10 @@ Runs a CL command and returns a `CallResult` object.
105105

106106
#### Parameters
107107

108-
| Name | Required | Type | Description |
109-
|:------------|:---------|:----------|:--------------------------------------------------------------------------------------------------------------|
110-
| command | ☑ | `String` | The CL command to run |
111-
| failOnError | ✖ | `boolean` | When `false`, the pipeline execution won't be stopped if the command execution has fails. Defaults to `true`. |
108+
| Name | Required | Type | Description |
109+
|:------------|:---------|:----------|:---------------------------------------------------------------------------------------------------------------|
110+
| command | ☑ | `String` | The CL command to run |
111+
| failOnError | ✖ | `boolean` | When `false`, the pipeline execution won't be stopped if the command execution has failed. Defaults to `true`. |
112112

113113
#### Returned value
114114

@@ -134,7 +134,35 @@ if (!result.successful) {
134134
135135
//Delete a library; carry on whatever happens
136136
ibmiCommand(command: "DLTLIB LIB($library)", failOnError: false)
137+
```
138+
139+
### ibmiShellExec
140+
141+
Runs a shell command through `QSH` and returns a `ShellExec` object.
142+
143+
#### Parameters
144+
145+
| Name | Required | Type | Description |
146+
|:------------|:---------|:----------|:-------------------------------------------------------------------------------------------------------------|
147+
| command | ☑ | `String` | The shell command to run |
148+
| failOnError | ✖ | `boolean` | When `false`, the pipeline execution won't be stopped if the shell execution has failed. Defaults to `true`. |
149+
150+
#### Returned value
151+
152+
A [`ShellExec`](#shellexec) object.
137153

154+
#### Example
155+
156+
```groovy
157+
//List and print all the file in /tmp
158+
def tempList = ibmiShellExec "ls /tmp"
159+
print tempList.output
160+
161+
//Copy something but do not stop if it fails
162+
def result = ibmiShellExec(command: "cp /something", failOnError: false)
163+
if (result.code != 0) {
164+
print "Copy failed but we carry on!"
165+
}
138166
```
139167

140168
### ibmiRunSQL
@@ -326,9 +354,9 @@ A [`Job`](https://javadoc.io/doc/net.sf.jt400/jt400/latest/com/ibm/as400/access/
326354

327355
```groovy
328356
def result = ibmiCommand "SBMJOB CMD(COMPILE...)"
329-
if(result.successful) {
357+
if (result.successful) {
330358
def job = result.getSubmittedJobs().getAt(0)
331-
if(job){
359+
if (job) {
332360
//Wait for the job and fail pipeline if it hits MSGW status
333361
ibmiWaitJob name: job.name, number: job.number, user: job.user, onMSGW: 'FAIL'
334362
}
@@ -338,6 +366,7 @@ if(result.successful) {
338366
## Enumerations
339367

340368
### OnMSGW
369+
341370
| Value | Description |
342371
|:-------|:-----------------------------------------------------|
343372
| FAIL | Stop the pipeline execution and marks it as failed. |
@@ -348,20 +377,31 @@ if(result.successful) {
348377
## Returned objects
349378

350379
### CallResult
351-
| Methods | Return type | Description |
352-
|:-------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
353-
| getMessages() | [`List`](https://docs.oracle.com/javase/8/docs/api/java/util/List.html)<[IBMiMessage](#ibmimessage)> | Returns the list of [IBMiMessage](#ibmimessage) generated during the command execution. |
354-
| getMessage(`String` messageId) | [IBMiMessage](#ibmimessage) | Look for the first [IBMiMessage](#ibmimessage) whose ID is `messageId` and returns it. Returns `null` if not found. |
355-
| getLastMessage() | [IBMiMessage](#ibmimessage) | Returns the last [IBMiMessage](#ibmimessage) generated by the command or `null` if there is no message. |
356-
| getPrettyMessages() | `String` | Returns a `String` resulting from the concatenation of every [IBMiMessage](#ibmimessage) returned by the command, one per line, formatted using this pattern: `[{id}][{severity}] {text}`. |
357-
| isSuccessful() | `boolean` | Returns `true ` if the command execution was successful, `false` otherwise. |
358-
| getSubmittedJobs() | [`List`](https://docs.oracle.com/javase/8/docs/api/java/util/List.html)<[IBMiJob](#ibmijob)> | Returns a list of [IBMiJob](#ibmijob) found by browsing the `CPC1221` messages from the call result. |
380+
381+
| Methods | Return type | Description |
382+
|:-------------------------------|:-----------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
383+
| getMessages() | [`List`](https://docs.oracle.com/javase/8/docs/api/java/util/List.html)<[IBMiMessage](#ibmimessage)> | Returns the list of [IBMiMessage](#ibmimessage) generated during the command execution. |
384+
| getMessage(`String` messageId) | [IBMiMessage](#ibmimessage) | Look for the first [IBMiMessage](#ibmimessage) whose ID is `messageId` and returns it. Returns `null` if not found. |
385+
| getLastMessage() | [IBMiMessage](#ibmimessage) | Returns the last [IBMiMessage](#ibmimessage) generated by the command or `null` if there is no message. |
386+
| getPrettyMessages() | `String` | Returns a `String` resulting from the concatenation of every [IBMiMessage](#ibmimessage) returned by the command, one per line, formatted using this pattern: `[{id}][{severity}] {text}`. |
387+
| isSuccessful() | `boolean` | Returns `true ` if the command execution was successful, `false` otherwise. |
388+
| getSubmittedJobs() | [`List`](https://docs.oracle.com/javase/8/docs/api/java/util/List.html)<[IBMiJob](#ibmijob)> | Returns a list of [IBMiJob](#ibmijob) found by browsing the `CPC1221` messages from the call result. |
389+
390+
### ShellExec
391+
392+
| Methods | Return type | Description |
393+
|:---------|:------------|:---------------------------------------------|
394+
| code() | `int` | The exit code returned by the shell command. |
395+
| output() | `String` | The output produced by the shell command. |
359396

360397
### IBMiMessage
361-
Extends [AS400Message](https://javadoc.io/doc/net.sf.jt400/jt400/latest/com/ibm/as400/access/AS400Message.html) and adds the method(s) below.
362-
| Methods | Return type | Description |
398+
399+
Extends [AS400Message](https://javadoc.io/doc/net.sf.jt400/jt400/latest/com/ibm/as400/access/AS400Message.html) and adds
400+
the method(s) below.
401+
| Methods | Return type | Description |
363402
|:----------------------|:------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
364-
| getSubstitutionDataAsString() | `String` | The AS400 message substitution data converted using current connection's [CharConverter](https://javadoc.io/doc/net.sf.jt400/jt400/latest/com/ibm/as400/access/CharConverter.html). |
403+
| getSubstitutionDataAsString() | `String` | The AS400 message substitution data converted using current
404+
connection's [CharConverter](https://javadoc.io/doc/net.sf.jt400/jt400/latest/com/ibm/as400/access/CharConverter.html). |
365405

366406
### IBMiJob
367407

@@ -385,12 +425,12 @@ Extends [AS400Message](https://javadoc.io/doc/net.sf.jt400/jt400/latest/com/ibm/
385425

386426
### SQLColumn
387427

388-
| Methods | Return type | Description |
389-
|:--------------|:------------|:--------------------------------------------------------------------------------------------------------------------|
390-
| getName() | `String` | The column's name. |
391-
| getTypeName() | `String` | The columns's database-specific type. name. |
392-
| getSize() | `int` | The column's size. |
393-
| getScale() | `int` | The number of digits to right of the decimal point. 0 is returned for data types where the scale is not applicable. |
428+
| Methods | Return type | Description |
429+
|:-----------|:------------|:--------------------------------------------------------------------------------------------------------------------|
430+
| name() | `String` | The column's name. |
431+
| typeName() | `String` | The columns's database-specific type. name. |
432+
| size() | `int` | The column's size. |
433+
| scale() | `int` | The number of digits to right of the decimal point. 0 is returned for data types where the scale is not applicable. |
394434

395435
### SQLRow
396436

0 commit comments

Comments
 (0)