integration-tests/jt400/README.adoc

=== External IBM i


To execute the tests against an external IBM i server, provide the connection information by setting environment variables

```
export JT400_URL=#jdbc_url
export JT400_USERNAME=#username
export JT400_PASSWORD=#password
```

or for Windows:

```
$Env:JT400_URL = "#jdbc_url"
$Env:JT400_USERNAME="#username"
$Env:JT400_PASSWORD="#password"
```

Tests using an external server are disabled until environmental property `JT400_URL` is present.

=== Mocked test

Mocked tests are enabled by default.
Unfortunately in case that mocked tests are enabled, the flat class path is forced for the Quarkus, which may influence
the tests.

Execution of mocked tests can be skipped by setting property `skip-mock-tests` to true (by adding parameter `-Dskip-mock-tests=true`).

=== How to configure an external server

Several objects (queues, user spaces, ..) have to be created in the external server to make testing successful.

The suggested approach is to create a test library. In the following text, the test library's name is `LIBRARY`

Download i-access client solutions from this https://www.ibm.com/support/pages/ibm-i-access-client-solutions[page].
Use the 5250 emulator option from the client and run the following command for library creation:

```
CRTLIB LIBRARY
```

==== Program call testing

Program call test reads the content of user space.

```
//interface for multiline commands
CALL QCMD

//creation of PROGCALL user space
CALL PGM(QSYS/QUSCRTUS) PARM(('PROGCALL  LIBRARY   ' (*CHAR 20))
        ('TEST      ' (*CHAR 10)) (16 (*INT 4))
        (' ' (*CHAR 1)) ('*ALL      ' (*CHAR 10))
        ('                ' (*CHAR 16)))

//value is set to hello camel
CALL PGM(QSYS/QUSCHGUS) PARM(('PROGCALL  LIBRARY   ' (*CHAR 20))
        (1 (*INT 4)) (16 (*INT 4))
        ('hello camel     ' (*CHAR 16))
        ('1' (*CHAR 1))  )
```

==== Message queue testing

Message queue can be created by following the command

```
CRTMSGQ LIBRARY/TESTMSGQ
```


Second queue is required for testing of inquiry messages:

```
CRTMSGQ LIBRARY/REPLYMSGQ
```

==== Data queue testing

Two data-queues are required for the testing. One created as `keyed=true` and one as `LIFO`.

```
//keyed data queue
CRTDTAQ DTAQ(LIBRARY/TESTKEYED) SEQ(*KEYED) KEYLEN(20) MAXLEN(100)

//LIFO data queue
CRTDTAQ DTAQ(LIBRARY/TESTLIFO) SEQ(*LIFO) MAXLEN(100)
```

==== Using different object names

If your test object names are different from the default ones, you can override default values via environmental variable

```
export JT400_LIBRARY=#library_if_not_LIBRARY
export JT400_LIFO_QUEUE=#lifoqueue_if_not_TESTLIFO.DTAQ
export JT400_KEYED_QUEUE=#lkeyedqueue_if_not_TESTKEYED.DTAQ
export JT400_MESSAGE_QUEUE=#messagequeue_if_not_TESTMSGQ.MSGQ
export JT400_MESSAGE_REPLYTO_QUEUE=#messagequeueinquiry_if_not_REPLYMSGQ.MSGQ
export JT400_USER_SPACE=#userspace_if_not_PROGCALL
```

or for Windows:

```
$Env:JT400_LIBRARY = "#library_if_not_LIBRARY"
$Env:JT400_LIFO_QUEUE="#lifoqueue_if_not_TESTLIFO.DTAQe"
$Env:JT400_KEYED_QUEUE="#lkeyedqueue_if_not_TESTKEYED.DTAQ"
$Env:JT400_MESSAGE_QUEUE="#messagequeue_if_not_TESTMSGQ.MSGQ"
$Env:JT400_MESSAGE_REPLYTO_QUEUE="#messagequeueinquiry_if_not_REPLYMSGQ.MSGQ"
$Env:JT400_USER_SPACE="#userspace_if_not_PROGCALL"
```

=== Clear queues after unexpected failures

If tests finishes without unexpected failure, tests are taking care of clearing the data.
In some cases data might stay written into the real server if test fails unexpectedly.
This state should might alter following executions.

To force full clear (of each queue) can be achieved by add ing parameter
```
-Dcq.jt400.clear-all=true
```
Be aware that with `-Dcq.jt400.clear-all=true`, the tests can not successfully finish in parallel run.

Usage of clear queues parameter is *strongly* suggested during development


==== Parallel runs and locking

Simple locking mechanism is implemented for the test to allow parallel executions.

Whenever test is started, new entry is  written into keyed data queue `JT400_KEYED_QUEUE` with the key `cq.jt400.global-lock` and entry is removed after the run.
Tests are able to clear this lock even if previous execution fails unexpectedly.