Creating a Request-Response WSBind file from a language structure

The temporary workspace

The JSON web services assistant requires a temporary workspace, so it uses the directory value that is specified in the TMPDIR environment variable. If TMPDIR is not specified the default /tmp is used. If TMPDIR is specified, it must be the location of a directory, and the user ID used to run the script must have read and write permission to this directory.

Parameter use

• LS-REQUEST and LS-RESPONSE must be defined, unless REQUEST-CHANNEL and RESPONSE-CHANNEL are defined. These pairs are mutually exclusive.
• You can specify the input parameters in any order.
• Each parameter must start on a new line.
• There must be no blanks or other whitespace characters between <name> and <value>, only the = symbol.
• If a parameter is too long to fit on a single line, use a backslash (\) character at the end of the line to indicate that the parameter continues on the next line. Everything, including spaces before the backslash is considered part of the parameter. For example:

  WSBIND=wsbinddir\
  /app1

  is equivalent to

  WSBIND=wsbinddir/app1

Parameter descriptions

CCSID=value

Specifies the CCSID that is used at run time to encode character data in the application data structure. The default value is EBCDIC CCSID 037 when TARGET-CICS-PLATFORM is zOS, IBM-i, VSE, or not specified, otherwise it is ASCII CCSID 437.

If a value is specified, it must be supported by Java™. For more information, see IBM® z/OS® Unicode Services User's Guide and Reference and Code pages.

If the CICS® application program specified on the PGMNAME parameter is defined in the CICS conversion table DFHCNV, then CCSID should be set to the value specified on the CLIENTCP parameter in the DFHCNV entry.

CHAR-OCCURS={STRING|ARRAY}

Specifies how character arrays in the language structure are mapped. For example, PIC X OCCURS 20. This parameter is only for use by COBOL language.

ARRAY

Character arrays are mapped to a JSON array so that every character is mapped as an individual JSON element.

STRING

Character arrays are mapped to a JSON string so that the entire COBOL array is mapped as a single JSON element.

CHAR-USAGE=NATIONAL|DBCS

In COBOL, the national data type, PIC N, can be used for UTF-16 or DBCS data. This setting is controlled by the NSYMBOL compiler option. You must set the CHAR-USAGE parameter on the assistant to the same value as the NSYMBOL compiler option to ensure that the data is handled appropriately. This parameter is typically set to CHAR-USAGE=NATIONAL when you use UTF-16.

DBCS

Data from PIC (n) fields is treated as UTF-16 encoded data.

NATIONAL

Data from PIC (n) fields is treated as DBCS encoded data.

CHAR-VARYING={NO|NULL|COLLAPSE|BINARY}

Specifies how character fields in the language structure are mapped. A character field in COBOL is a Picture clause of type X, for example PIC(X) 10; a character field in C/C++ is a character array. You can select these options:

NO

Character fields are mapped to a JSON string and are processed as fixed-length fields. The maximum length of the data is equal to the length of the field.

This value does not apply to Enterprise and Other PL/I language structures.

NULL

Character fields are mapped to a JSON string and are processed as null-terminated strings. CICS TG adds a terminating null character when transforming from a JSON message. The maximum length of the character string is calculated as one character less than the length indicated in the language structure. NULL is the default value for the CHAR-VARYING parameter for C/C++.

This value does not apply to Enterprise and Other PL/I language structures.

COLLAPSE

Character fields are mapped to a JSON string. Trailing white space in the field is not included in the JSON message. The inbound JSON message is parsed to remove all leading, trailing, and embedded white space. For COBOL and PL/I, the default is COLLAPSE.

BINARY

Character fields are mapped to a JSON string that contains base64 encoded data and are processed as fixed-length fields.

For more information about handling variable-length values and white space, see Support for variable-length values and white space.

CONTID=value

In a service provider, specifies the name of the container that holds the top-level data structure that is used to represent a JSON message.

The length of the container that CICS TG passes to the target application program is the greater of the lengths of the request container and the response container.

DATA-TRUNCATION={DISABLED|ENABLED}

Specifies if variable length data is tolerated in a fixed-length field structure:

DISABLED

If the data is less than the fixed length that CICS TG is expecting, then CICS TG rejects the truncated data and issues an error message.

ENABLED

If the data is less than the fixed length that CICS TG is expecting, then CICS TG tolerates the truncated data and processes the missing data as null values.

DATETIME={UNUSED|PACKED15}

Specifies if potential ABSTIME fields in the high-level language structure are mapped as time stamps:

PACKED15

Packed decimal fields of length 15 (8 bytes) are treated as CICS ABSTIME fields, and mapped as timestamps.

UNUSED

Packed decimal fields of length 15 (8 bytes) are not treated as timestamps.

JSON-SCHEMA-REQUEST=value

This parameter is mandatory.

The value indicates the filename where the request JSON Schema is stored.

JSON-SCHEMA-RESPONSE=value

This parameter is mandatory.

The value indicates the filename where the response JSON Schema is stored.

LANG=COBOL

Specifies that the programming language of the high-level language structure is COBOL.

LANG=PLI-ENTERPRISE

Specifies that the programming language of the high-level language structure is Enterprise PL/I.

LANG=PLI-OTHER

Specifies that the programming language of the high-level language structure is a level of PL/I other than Enterprise PL/I.

LANG=C

Specifies that the programming language of the high-level language structure is C.

LANG=CPP

Specifies that the programming language of the high-level language structure is C++.

LOGFILE=value

The fully qualified path of the file into which the JSON web services assistant writes its activity log and trace information. The JSON web services assistant creates the file, but not the directory structure, if it does not exist.

Typically, you do not use this file, but it might be requested by the IBM service organization if you encounter problems with the JSON web services assistant.

LS-CODEPAGE=value

Specifies the code page that is used for the files specified in the LS-REQUEST and LS-RESPONSE parameters, where value is a CCSID number or a Java code page number. If this parameter is not specified, the current code page is used.

For example, LS-CODEPAGE=037.

LS-REQUEST=value

Specifies a filename that the JSON web services assistant uses to generate the names of the files that contain the high-level language structures for the web service request, which is the input data to the application program.

This is a mandatory parameter, unless you specify REQUEST-CHANNEL and RESPONSE-CHANNEL.

If you specify LS-REQUEST, you must also specify LS-RESPONSE. The value that is specified must be different to the value specified on the LS-RESPONSE parameter.

LS-RESPONSE=value

Specifies a filename that the JSON web services assistant uses to generate the names of the files that contain the high-level language structures for the web service response, which is the output data from the application program.

This is a mandatory parameter, unless you specify REQUEST-CHANNEL and RESPONSE-CHANNEL..

If you specify LS-RESPONSE you must also specify LS-REQUEST. The value that is specified must not be the same as the value specified on the LS-REQUEST parameter.

MAPPING-MODE=LS2JS

This parameter is mandatory.

Indicates mapping from language structure to JSON.

PGMINT={CHANNEL|COMMAREA}

For a service provider, specifies how CICS TG passes data to the target application program:

CHANNEL

CICS TG uses a channel interface to pass data to the target application program.

• The channel can contain multiple containers. Use the REQUEST-CHANNEL and RESPONSE-CHANNEL parameters. Do not specify LS-REQUEST, or LS-RESPONSE.

COMMAREA

CICS TG uses a communication area to pass data to the target application program.

When the target application program has processed the request, it must use the same mechanism to return the response. If the request was received in a communication area, then the response must be returned in the communication area; if the request was received in a container, the response must be returned in a container. The length of the communication area or container that CICS TG passes to the target application program is the greater of the lengths of the request communication area or container and the response communication area or container.

PGMNAME=value

Specifies the name of the CICS PROGRAM resource for the target application program that is exposed as a web service.

REQUEST-CHANNEL=value

This parameter is optional but if you do not specify REQUEST-CHANNEL and RESPONSE-CHANNEL, then you must specify LS-REQUEST and LS_RESPONSE. If you do specify REQUEST-CHANNEL and RESPONSE-CHANNEL, then you cannot specify LS-REQUEST and LS_RESPONSE.

Specifies the name and location of a channel description document. The channel description describes the containers that the web service provider application can use in its interface when it receives a JSON message from a web service requester. The channel description is a JSON document that must conform to the CICS supplied channel schema.

RESPONSE-CHANNEL=value

This parameter is optional but if you do not specify REQUEST-CHANNEL and RESPONSE-CHANNEL, then you must specify LS-REQUEST and LS_RESPONSE. If you do specify REQUEST-CHANNEL and RESPONSE-CHANNEL, then you cannot specify LS-REQUEST and LS_RESPONSE.

Specifies the name and location of a channel description document. The channel description describes the containers that the web service provider application can use in its interface when it sends a JSON response message to a web service requester. The channel description is a JSON document that must conform to the CICS supplied channel schema.

STRUCTURE=(request,response)

For C and C++ only, specifies the names of the high-level structures that are contained in the files that are specified in the LS-REQUEST and LS-RESPONSE parameters:

request

Specifies the name of the high-level structure that contains the request when the LS-REQUEST parameter is specified. The default value is DFHREQUEST.

If you specify a value, the file must contain a high-level structure with the name that you specify or a structure named LS-RESPONSE if you do not specify a name.

response

Specifies the name of the high-level structure that contains the response when the LS-RESPONSE parameter is specified. The default value is DFHRESPONSE.

If you specify a value, the file must contain a high-level structure with the name that you specify or a structure named LS-RESPONSE if you do not specify a name.

SYNCONRETURN={NO|YES}

Specifies whether the remote web service can issue a sync point.

NO

The remote web service cannot issue a sync point. This value is the default. If the remote web service issues a sync point, it fails with an ADPL abend.

YES

The remote web service can issue a sync point. If you select YES, the remote task is committed as a separate unit of work when control returns from the remote web service. If the remote web service updates a recoverable resource and a failure occurs after it returns, the update to that resource cannot be backed out.

TARGET-CICS-PLATFORM={zOS|AIX|IBM-i|VSE|LinuxI|Windows}

Specifies the platform for the CICS server that receives requests from this web service.

zOS

CICS Transaction Server for IBM z/OS

AIX

IBM TXSeries® for Multiplatforms on IBM AIX®

IBM-i

CICS Transaction Server for i

VSE

CICS Transaction Server for VSE/ESA

LinuxI

IBM TXSeries for Multiplatforms on Intel Linux®

Windows

IBM TXSeries for Multiplatforms on Microsoft Windows

For IBM z/OS, data is aligned on the IBM z/OS default boundaries. For all other platforms data is aligned on natural boundaries:

Table 1. Natural boundaries

Data type	Storage (bytes)	Alignment (bytes)
Short	2	2
Int	4	4
Long	8	8
Float	4	4
Double	8	8

TRANSACTION=name

Specifies the 1-4 character name of a transaction identifier that is passed in the EIBTRNID field of the exec interface block (EIB). If the web service is configured with the defaultmirror property set to No, the value of this parameter also specifies the name of the mirror transaction which is attached when the CICS program is called. The value of this parameter can be overridden by the transactionid property in the CICS TG configuration file.

If you specify TRANSACTION you must also specify URI.

Acceptable characters: A-Z a-z 0-9 $ @ # _ < >

URI=value

Specifies the relative URI that a client uses to access the web service. The value of this parameter can be overridden by the uri property in the CICS TG configuration file.

The URI consists of a path and an optional query string. If the URI path ends with *, the web service matches any request URI that starts with the specified path. The trailing * character is not considered part of the URI to match. If the URI contains a query string, the web service matches requests for the URI that contains all of the specified query string parameters in any order.

USERID=id

Specifies a 1-8 character user ID. The mirror transaction is attached under this user ID when the CICS program is called if the web service client does not provide user credentials.

Acceptable characters: A-Z a-z 0-9 $ @ #

If you specify USERID you must also specify URI.

WSBIND=value

The fully qualified path of the web service binding file. The JSON web services assistant creates the file, but not the directory structure, if it does not exist. The file extension is .wsbind.