ZCOM (2.0.5)

Access to IBM Power Systems

The ZCOM API has been designed as a simple yet powerful way to access programs and data that reside on back-end IBM Power systems. 

ZCOM endpoints support the following categories of transactions:

1. Call Programs
2. Call Service Procedures
3. Download from IBM Files
4. Upload to IBM Files
5. Health Check

Getting Started

Obtaining Credentials and Keys

You will need logon credentials (user ID and passsword), plus an encryption key if you want to send encrypted transactions and the server has been setup with AES keys.

Authentication

Authentication information should normally be included in the body of the POST request:

"authorization": {
  "authtype": "as400"
  "username": "testuser",
  "password": "Secret$Pwd",
}

However, it is also possible to specify authentication credentials in a standard BASIC authentication header:

Authorization: Basic dXNlcm5hbWU6dXNlcnBhc3N3b3Jk

Connection Pools

There are a few different ways to manage HTTP connection pools with ZCOM:

Pools Maintained By	Settings or Options	Explanation
Locally by ZCOM	"forcehttp10": true in config - or all clients use HTTP 1.0 connections	no single client can monopolize a connection, connection is established, work performed, and connection closed
Remotely by other servers	do not force HTTP 1.0 connections	remote servers maintain connection pools directly to ZCOM, they are closed when server closes them or by ZCOM when idle
By reverse proxy (NGINX)	do not force HTTP 1.0 connections - configure proxy to maintain downstream connection pools	reverse proxy can terminate SSL, maintains upstream connection pools, and maintains downstream connections to ZCOM

Encryption

The server controls which transactions require encryption, which can be by source IP address, transaction name, or a combination of the two.

Transaction payloads are encrypted and then encoded with base64. An example payload would look something like this:

rzfFr1avSHF8O8i3Ojm+dT5jY9xYB/jpekQPR+jVXRYB8poVRtqRG93mdc92FMMaTSZSOBqscCkqw9ZQ
tcbmuEV3ZBhbzA2I39pUC3Di+N6b6S9Drp7jjCgOGRliRMKfffv2FXyv8Fnx+oZKTLQpbEsowzIBFMVX
jPan4saTNCuKmO+AZzhk4wCXLWIIqO50JyPVdE0auWAAJOB8RMM63doEF/5sT5yJtERSolZqM7vE77xV
v+9UwmxkJU1yuWldOpM6FdMfqX3gEmlYkl2ve7NyoT7r6KdyerqhejzcrdW3uq1d4PHwdoi+Rep4qlUp
r84wzUEGTG6ded27ekBDNNih/n0+imIK7WU03Yw1gvQDYJragVlkI/r1roKh0Z+zcI3YerR9gZfJikJc
I5DECV61daxKhwM4KEyXrhHicwA=

Compression

The server supports compresison for HTTP response bodies, but requires a header that lists which compression methods the client supports. The response will contain which compression method was used in a separate header:

---- REQUEST header ----
X-Accept-Compression: deflate

---- RESPONSE header ----
X-Response-Compression: deflate

Both 'deflate' and 'zlib' formats are supported.

Duplicate Detection

The server is capable of detecting requests that are exact duplicates of previous requests, and regenerating a response. Duplicate checking is enabled using an additional request element: "dupcheck", or the host configuration for a transaction can specify that duplicate checking should always be performed. The number of seconds in the duplicate window is determined in the configuration settings, but will default to 180 seconds.

When a transaction is found to be a duplicate, one additional element ("duplicate") will be added to the response body. Transactions that are not duplicates will not contain the "duplicate" element in the response.

---- REQUEST ----
{
 "authorization": {
    "authtype": "ldap",
    "password": "SecretPwd",
    "username": "billh"
 },
 "request": {
    "library": "*libl",
    "program": "testtrx",
    "rsplen": 1024,
    "parmdata": "1234567890",
    "dupcheck": true
 } 
}  

---- RESPONSE ----
{
  "httpstatus": 200,
  "exception": false,
  "duplicate": true,
  "response": "transaction response here"
}    

Mapping Support

Called IBM i programs often do not support JSON parameters. To facilite the conversion of JSON requests to non-JSON program requests, and non-JSON program responses to JSON responses, mapping support has been included in this version of ZCOM.

Request maps are strings that provide instructions for how to convert a JSON document into a program request. Response maps are strings that provide instructions for how to convert program responses into a JSON document. String maps are specified in the "maps" section of the server configuration file:

"maps": [
   {
   "name": "REQMAP-PGM1",
   "value": "MSGTYP:<FS>CUSTID:<FS>AMT:",
   },
   {
    "name": "RSPMAP-PGM1",
    "value": "AUTHNO:<FS>LIMIT:<FS>BALANCE:",
   },
]

The request map looks for three fields in the JSON document, and will format those three fields as a field-separated ("") request string. The response map will take a response string that contains field separators, and will map that into a JSON document with matching field names.

Content-Type

The server will respond to requests using the same format as was auto-detected in the request JSON payload. Client requests and server responses can be in any of three formats:

Format of Request Payload	Request 'Content-Type'	Response 'Content-Type'
Clear-Text JSON	none or 'application/json'	'application/json'
Base64 JSON	none or 'text/plain'	'text/plain'
Encrypted JSON	none or 'text/plain'	'text/plain'
Any request that allows compression	any	'text/plain'

Supported File Systems and CCSID's

The server can retrieve or send data from/to two supported iSeries file systems:

• IFS File System. This file system normally contains stream data. These files are not part of a database, and cannot be be queried or retrieved in separate columns. CCSID's for binary IFS files are ignored, the data is written and read without translation.

  • PutFile (text): When a ccsid is specified for a putfile to an IFS text file, the server will attempt to translate the supplied data from the default ccsid of the job (always 037), to the character set represented by the ccsid. If a translation table does not exists for the job-to-file ccsid mapping, a "conversion error" will be produced. If the ccsid is missing, it will default to 037. CCSID is the encoding for the file and file contents on the system you are uploading to.

  • GetFile (text): When a ccsid is specified for a getfile from an IFS text file, use one of the supported ASCII CCSID's (1208, 1252, 1250, 437), or use an EBCDIC CCSID such as 037. Use of an ASCII CCSID will cause the data to be returned in ASCII, while using an EBCDIC such as 037 will cause the text data to be returned in rows of EBCDIC data, encoded as base64. Not specifying a ccsid will cause the system to use a CCSID of 1252. CCSID is the encoding for data from the file you are downloading from.

  File specifications for IFS downloads use the 'filename' parameter.

• QSYS File System. This file system normally contains data organized into rows and columns. Sometimes only a single column is present when the file is a "program described" file. CCSID's for binary QSYS files are ignored, the data is written and read without translation. Normally, QSYS files have CCSID's of 65535, which represents binary or HEX encoding.

  • PutFile (text): ASCII CCSID's are not supported when requesting a putfile to a QSYS text file. The server will attempt to translate the supplied data to ccsid 037 before writing text files. If the data needs to be encoded with something other than 037, you will need to perform a binary PutFile, with the supplied data in Base64 format using the correct encoding method.

  • Uploading Multiple Records (text): A PutFile to a QSYS flle that contains multiple records should have "end-of-record" indicated in one of two ways:

    • if the filedata is sent as ASCII text, use the '\n' escape sequence to indicate end-of-record.
    • if the filedata is sent as base64 ASCII data, use the 0x15 character to indicate end-of-record. You may also optionally use the '\n' sequence encoded as base64.

  • GetFile (text): Ccsid's are ignored when retrieving files from the QSYS file system. All text file requests will be returned in ASCII, and all binary file requests will be returned in EBCDIC BASE64.

  File specifications for QSYS downloads can use either the 'filename' parameter or the 'filesql' parameter. The SQL in requests can use several enhancements to the way SQL requests are normally processed:

  • if the library name (schema) for the file is dependent on the job's library list, you can use *LIBL.FILENAME syntax.

  • if the file contains multiple members, you an use the FILENAME(MBRNAME) syntax.

Execute an external program or service procedure on the IBM Power system.

• External programs can be any ILE or OPM program, written in any language. The format of the parms to an external program can consist of a single or multiple parameters (see "Host Programs").
• Service procedures are exported by service programs, which are bound by reference into the server program itself.

Retrieve data from an IBM host system. optionally converting to another CCSID. The following file types are supported:

• Integrated File System (IFS)
• Library File System (QSYS)
• SQL Retrieval from DB2 Tables

Upload data to an IBM host system. optionally converting to another CCSID. The following file types are supported:

• Integrated File System (IFS)
• Library File System (QSYS)

Health check for ZCOM server.

This model is used to specify authorization information

This model is used to specify requests for program calls when program parameters are a fixed string:

Use this model when program parameters are a JSON object:

This model is used to specify request information for procedure calls wnen parameters are a JSON object:

This model is used to specify request information for procedure calls wnen parameters a fixed string:

This model is used to return fixed string responses:

This model is used to return JSON object responses. This is an example only, your response will vary:

This model is used to request a download of a file or tabke from an IBM host system.

• Get by file name:

• Get by SQL query:

This model is the response to a request for a file download.

• Get by file name:

• Get by SQL query:

This model is used to request an upload of data to a file on the IBM host system:

This model is the response to a request for a file upload:

GETFILE IFS/QSYS File Systems

ZCOM can access data in a variety of different file systems and data formats:

File System	Type	Normally Contains	Example
IFS	PC or Stream	Binary or Text	filename: "/home/herron/testifs.txt"
QSYS	Program Defined	Text Rows Single Field	filename: "herron/test(test)""
QSYS	Externally Defined	Rows and Columns	filesql: "select * from *libl.herron.testdb"

EXAMPLE: Download a text file from either the IFS or QSYS file systems. Omit the requested CCSID to let the system figure out how best to handle text translation. Specifying any of the supported ASCII CCSID's (1208, 1252, 1250 or 437) works the same as allowing the system to automatically handle translation:

---- REQUEST ----
{
 "authorization": {
    "authtype": "ldap",
    "password": "SecretPwd",
    "username": "billh"
 },
 "request": {
    "filename": "/home/HERRON/testfile.txt",
    "filetype": "text"
 } 
}  

---- RESPONSE ----
{
  "httpstatus": 200,
  "exception": false,
  "response": [
    "Line 1",
    "Line 2",
    "Line 3"
  ]
}    

EXAMPLE: Download a file from the IFS but in binary format (no CCSID translation). It is assumed that you will do the decoding yourself:

---- REQUEST ----
{
 "authorization": {
    "authtype": "ldap",
    "password": "SecretPwd",
    "username": "billh"
 },
 "request": {
    "filename": "/home/HERRON/testfile.txt",
    "filetype": "binary"
 } 
}  

---- RESPONSE ----
{
 "httpstatus": 200,
 "exception": false,
 "response": "dGVzdGluZyAxDQp0ZXN0aW5nIDINCnRlc3RpbmcgMw0K"
}    

EXAMPLE: Download a text file from the IFS, but specify an EBCDIC CCSID to have the data returned in the native server CCSID without translation. The only CSSID supported for this use case is 037:

---- REQUEST ----
{
 "authorization": {
    "authtype": "ldap",
    "password": "SecretPwd",
    "username": "billh"
 },
 "request": {
    "filename": "/home/HERRON/testfile.txt",
    "filetype": "text",
    "ccsid": 037
 } 
}  

---- RESPONSE ----
{
  "httpstatus": 200,
  "exception": false,
  "response": [
    "o4Wio4mVh0Dx",
    "o4Wio4mVh0Dy",
    "o4Wio4mVh0Dz"
  ]
}    

PUTFILE IFS/QSYS File Systems

EXAMPLE: Upload a multi-line text file to the IFS. Files in the IFS are normally marked as 1252 (Latin-1 for Windows) or 1208 (UTF-8). If the CCSID is omitted, the file will be created with the default CCSID of the server (037, or US EBCDIC):

---- REQUEST ----
{
 "authorization": {
    "authtype": "ldap",
    "password": "SecretPwd",
    "username": "billh"
 },
 "request": {
    "filename": "/home/HERRON/testput.txt",
    "filedata": "line1\nline2\nline3\n",
    "filetype": "text",
    "addreplace": "replace",
    "ccsid": 1208
 } 
}  

---- RESPONSE ----
{
 "httpstatus": 200,
 "exception": false,
 "response": "File successfully uploaded (18 bytes)"
}   

NOTE: use escape sequences to indicate new lines (\n) or carriage returns (\r) in the file text.

EXAMPLE: Upload a multi-line text file to the QSYS/library file system. Databases (files) in the library file system are normally marked as having CCSID 65535 when they are internally desscribed, and CCSID of 037 when they are externally described. This means the CCSID is ignored if specified for a QSYS file upload:

---- REQUEST ----
{
 "authorization": {
    "authtype": "ldap",
    "password": "SecretPwd",
    "username": "billh"
 },
 "request": {
    "filename": "herron2/test99(test99)",
    "filedata": "line1\nline2\nline3\n",
    "filetype": "text",
    "addreplace": "replace",
    "lrecl": 132
  } 
}  

---- RESPONSE ----
{
 "httpstatus": 200,
 "exception": false,
 "response": "File successfully uploaded (18 bytes)"
}   

NOTE: You can upload to both internally and externally defined files. However, when uploading to files that do not exist, only internally defined files can be dynamically created, which requires the 'lrecl' (logical record length) parameter.

EXAMPLE: Upload a binary file to the IFS/QSYS file system. File data must be in BASE64 format (binary):

---- REQUEST ----
{
 "authorization": {
    "authtype": "ldap",
    "password": "SecretPwd",
    "username": "billh"
 },
 "request": {
    "filename": "/home/HERRON/testput.txt",
    "filedata": "bGluZTENCmxpbmUyDQpsaW5lMw0K",
    "filetype": "binary",
    "addreplace": "replace",
    "ccsid": 1208 
 } 
}  

---- RESPONSE ----
{
 "httpstatus": 200,
 "exception": false,
 "response": "File successfully uploaded (21 bytes)"
}    

NOTE: ASCII files should use HEX line terminators '0D0A', while EBCDIC CCSID files should use HEX line terminators '0D25'. It is important to use the correct CCSID when uploading IFS binary files (missing CCSID will cause the file to be marked as having the default CCSID of 37). CCSID's are ignored when uploading to files in the QSYS/library file system.

CallPgm or CallSrvPgm

ZCOM can call both external programs (CallPgm) and bound service programs (CallSrvPgm):

Program Type	Parmdata Format	Example Parmdata	Example Response
CallPgm	Fixed String	"parmdata": "question"	"response": "answer"
CallSrvPgm	JSON Data	"parmdata": { "fld1": "question1" "fld2": "question2" }	"response": { "fld1": "answer1" "fld2": "answer2" }

EXAMPLE: Call an external program, passing it a single string, and receiving a single string in response:

---- REQUEST ----
{
 "authorization": {
    "authtype": "ldap",
    "password": "SecretPwd",
    "username": "billh"
 },
 "request": {
    "library": "*libl",
    "program": "testtrx",
    "rsplen": 1024,
    "parmdata": "1234567890",
 } 
}  

---- RESPONSE ----
{
  "httpstatus": 200,
  "exception": false,
  "response": "texttrx answer here!"
}    

NOTE: calls to external programs require the length of the response string (rsplen). In the example above, the expected length of the response string is 1024 characters (the maximum size is 32,767). As an alternative, the default response length can be setup in the configuration file for that transaction.

Call a service program, passing it a JSON object, and receving a JSON object in return:

---- REQUEST ----
{
 "authorization": {
    "authtype": "ldap",
    "password": "SecretPwd",
    "username": "billh"
 },
 "request": {
    "library": "*libl",
    "program": "testjson",
    "rsplen": 1024,
    "parmdata": {
      "testreq": "1234567890"
    },
 } 
}  

---- RESPONSE ----
{
  "httpstatus": 200,
  "exception": false,
  "response": {
      "response1": "1234567890",
      "response2": "abcdefghij",
  },
}    

NOTE: maximum size of request and response parameters is application-defined. The IBM system enforces a limit for single character strings for RPG programs of 16,773,104 bytes.

IBM Host Program Parameters

The interface to externally called programs on the host system should be standardized using one of the following formats:

Single Parameter Format

Unhandled exceptions in the called program will be monitored by ZCOM. The single-parameter host program format is the default unless otherwise specified in the configuration file.

Parm Nbr	Purpose	Type	Min Len	Max Len
1	Input/Output parameter	Char	1	32767

Three Parameter Format

Although unhandled exceptions will be still monitored by ZCOM, this format provides a way for the called program to pass back its own error information.

Parm Nbr	Purpose	Type	Min Len	Max Len
1	Indicates error detected (0 or 1)	Char	1	1
2	Error message if applicable	Char	132	132
3	Input/Output parameter	Char	1	32767

For all host programs, the maximum size of the returned data needs to be specified when configuring this transaction in the "transactions" portion of the configuration file, or you can specify "rsplen" in the program call request.

IBM Host Service Procedure Parameters

The interface to service procedures referenced by the server can be completely customized, but the calling and response parameters must be coded into the ZCOM source program (ZCOMWORKER) and a custom version recompiled.