Stuart: Copy of PVTstub.odt from Mark's user docs

2021-10-07T08:51:24Z

Copy of PVTstub.odt from Mark's user docs

New page

<noinclude>{{nav/ACS Test Harness}}</noinclude>
== PVT Stub ==
The PVT stub utilises the Python CIS simulator to return defined responses to PDD and DCI messages sent via ACS.

Rules defining which message to return for a particular PDD/DCI transaction are configured in a configuration file. Messages themselves are contained in individual text files (base64 encoded EBCDIC for PDD, ASCII XML for DCI).

A bash script is run to invoke the simulator on a particular port, the simulator reads the configuration file and processes requests sent to it accordingly.

An instance of the simulator acts as a swimlane, but can process messages from multiple applications/services. Multiple simulators can be run concurrently on different ports, to simulate multiple swimlanes.

=== Install ===
A minimal install of the simulator requires the following:
* The simulator Python package (optionally added to the Python path ($PYTHONPATH))
* A folder to contain the config and start script
* A folder to contain the message files
* A folder to contain test data

See the pvtstub.zip file for an example install (containing cissim, serve, messages and test folders).

=== Configuration ===
The configuration file contains the following sections:
* [CONFIG] – to define the folder containing the reply messages
* [STATIC-PARAMS] – to define parameter values to be substituted at runtime
* [NAMESPACES] – to define namespaces for DCI message fields (not currently used)
* [REPLACEMENTS] to define rules for determining which reply message to return for a given request message, optionally making substitutions in the reply message

The replacement entries contain the following details:
* service/systemid – the service for PDD calls, the systemid for DCI calls
* transaction – the transaction identifier for a particular transaction type (see appendix)
* transaction file – the file containing the PDD or DCI message
* searches (optional) – zero, one or more search parameters
* replacements (optional) – zero, one or more replacement parameters

Searches refer to fields in the request message, and define values to check those fields against.
Replacements refer to fields in the reply message and define values to replace the content of those fields with.

See the example serve/configfile.stub.pvt for details of how to configure searches and replacements.

The transaction files can be viewed and edited using Python simulator utilities. Running pdedit.py against a reply file allows editing of the content, both the header and the payload.

==== Configuration test ====
To test whether a configuration file is coherent, for instance that the searches and replacements are correct and refer to valid layout fields, you can run the simulator in check mode by supplying a port value of 0. This will process the configuration file and report what it post-processes it to, including showing any errors, then immediately exit.

Once you have a configuration file that loads successfully, you can run the simulator and call it directly using Python simulator utilities to check each transaction. Example calls are shown in test/testcall.sh in the example test folder. Running the pdcall.py utility against an input message:
* Displays the request message in layout format (optionally allowing edit)
* Calls the simulator
* Displays the reply message in layout format (optionally allowing edit)

=== Run ===
The simulator should be run on the ACS VM(s).

You usually run the simulator in the background and leave it running, see the example bash script serve/pvtstub.sh for how to do that and send its output to a log file. You can also run it in the foreground when testing the configuration. To stop the simulator kill its PID.

To configure ACS to talk to the stub, set the PDD and DCI URLs in /opt/osmp/fdacs/conf/common/acs/fdacs.ini for the required services to point to localhost:<simport> (instead of np-cel-pri:<slport>). You will need to restart ACS after updating the ini file.

The simulator(s) can be started and stopped independently of ACS.

=== Tips ===
* For PDD:
** When creating reply messages:
*** You can create error scenarios by setting the apporpriate fields in the W90 header
** When calling from the command line:
*** Make sure you set the service identifier in all three places in the W80 header (W80-E1-INIT-SERVICE, W80-E3B-INFR-TPSVCE-NME, W80-L1-FULL-UNAME)
*** If using the request header to find the NINO, make sure you set it in W80-R1C-DAM-RQST-FN-KEY
*** For PD001 calls, set the calling dialog to the appropriate one for the application in W80-E1-PROCESS-NAME
* For DCI:
** Make sure you use the correct namespace for fields
* COBOL layouts:
** PDD:
*** COBOL layouts for each record type can be listed by running the cissim/getfieldoffset.py utility (edit that code to add a line for the required layout, setting the field to DUMMY). Alternatively, you can run the pdedit.py utility against an empty file
** DCI:
*** Request and reply XML can be found in the cissim/pdlayouts folder

=== Appendix ===
* Transaction identifiers:

Noctam/DWP/ACS Test Harness/Existing System/CISSIM/PVTstub.odt - Revision history

Stuart: Copy of PVTstub.odt from Mark's user docs