Creating a RESTful WSBind file

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 in IBM® z/OS® UNIX System Services, and the user ID used to run the job must have read and write permission to this directory.

Parameter use

• 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.
• A parameter, and its continuation character, if you use one, must not extend beyond column 72; columns 73 - 80 must contain blanks.
• 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

LS-RESTFUL=\
 //'USERID.PROJECT.COBOL(RESTFUL)'

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.

If a value is specified, it must be supported by Java™. For more information, see IBM z/OS Unicode Services User's Guide and ReferenceIBM z/OS Unicode Services User's Guide and Reference and Code pagesCICS Transaction Gateway: Programming Reference.

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-MULTIPLIER={1|value}

Specifies the number of bytes to allow for each character. The value of this parameter can be a positive integer in the range of 1 - 2,147,483,647. All nonnumeric character-based mappings, are subject to this multiplier. Binary, numeric, zoned, and packed decimal fields are not subject to this multiplier.

This parameter can be useful if, for example, you are planning to use DBCS characters where you might opt for a multiplier of 3 to allow space for potential shift-out and shift-in characters around every double-byte character at run time.

When you set CCSID=1200 (indicating UTF-16), the only valid values for CHAR-MULTIPLIER are 2 or 4. When you use UTF-16, the default value is 2. Use CHAR-MULTIPLIER=2 when you expect application data to contain characters that require 1 UTF-16 encoding unit. Use CHAR-MULTIPLIER=4 when you expect application data to contain characters that require 2 UTF-16 encoding units.

Note: Setting CHAR-MULTIPLIER to 1 does not preclude the use of DBCS characters, and setting it to 2 does not preclude the use of UTF-16 surrogate pairs. However, if wide characters are routinely used then some valid values will not fit into the allocated field. If a larger CHAR-MULTIPLIER value is used, it can be possible to store more characters in the allocated field than are valid in the XML. Care must be taken to conform to the appropriate range restrictions.

CHAR-VARYING=NO|NULL|YES

Specifies how variable-length character data is mapped. Variable-length binary data types are always mapped to either a container or a varying structure. If you do not specify this parameter, the default mapping depends on the language specified. You can select these options:

NO

Variable-length character data is mapped as fixed-length strings.

NULL

Variable-length character data is mapped to null-terminated strings.

YES

Variable-length character data is mapped to a CHAR VARYING data type in PL/I. In the COBOL, C, and C++ languages, variable-length character data is mapped to an equivalent representation that comprises two related elements: data-length and the data.

CHAR-VARYING-LIMIT=32767|value

Specifies the maximum size of binary data and variable-length character data that is mapped to the language structure. If the character or binary data is larger than the value specified in this parameter, it is mapped to a container and the container name is used in the generated language structure. The value can range from 0 to the default 32,767 bytes.

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=PACKED15|STRING

Specifies how JSON date-time elements are mapped to the language structure.

PACKED15

The default is that any JSON date-time element is processed as a time stamp and is mapped to CICS ABSTIME format.

STRING

The JSON date-time element is processed as text.

DEFAULT-CHAR-MAXLENGTH=255|value

Specifies the default array length of character data in characters for mappings where no length is implied in the web service description document. The value of this parameter can be a positive integer in the range of 1 - 2,147,483,647.

HTTP-METHODS={GET|POST|PUT|DELETE|HEAD},{GET|POST|PUT|DELETE|HEAD},*

This is an optional parameter.

The default value is for GET, POST, PUT, and DELETE to be set, which tells JSON web services assistant that the application supports the four main RESTful operations.

If a value is provided, JSON web services assistant builds a WSBind file in which only the explicitly specified HTTP methods are accepted.

If an application wants to implement the HEAD method, it must deliberately opt-in to doing so. By default JSON web services assistant assumes that the application does not support incoming HTTP HEAD methods.

If a JSON client attempts to use an unsupported HTTP method, CICS TG responds with an HTTP 405 response.

INLINE-MAXOCCURS-LIMIT=1|value

Specifies whether inline variable repeating content is used based on the maxItems JSON Schema keyword. Variably repeating content that is mapped inline is placed in the current container with the rest of the generated language structure. The variably repeating content is stored in two parts, as a counter that stores the number of occurrences of the data and as an array that stores each occurrence of the data. The alternative mapping for variably repeating content is container-based mapping, which stores the number of occurrences of the data and the name of the container where the data is placed. Storing the data in a separate container has performance implications that might make inline mapping preferable.

The value of INLINE-MAXOCCURS-LIMIT can be a positive integer in the range of 0 - 32,767. A value of 0 indicates that inline mapping is not used. A value of 1 ensures that optional elements are mapped inline. If the value of the maxOccurs attribute is greater than the value of INLINE-MAXOCCURS-LIMIT, container-based mapping is used; otherwise inline mapping is used.

When you decide whether you want variably repeating lists to be mapped inline, consider the length of a single item of recurring data. If few instances of long length occur, container-based mapping is preferable; if many instances of short length occur, inline mapping is preferable.

JSON-SCHEMA-RESTFUL=value

This parameter is mandatory.

The value specifies the UNIX System Services location 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 IBM z/OS UNIX name of the file into which 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 in the partitioned data set members that are specified in the PDSMEM parameter, where value is a CCSID number or a Java code page number. If this parameter is not specified, the IBM z/OS UNIX System Services code page is used. For example, you might specify LS-CODEPAGE=037.

LS-RESTFUL

Specifies the name of the partitioned data set member, sequential file, or UNIX System Services location for the generated high-level language structures. For a service provider, the web service request is the input to the application program.

MAPPING-MODE=JS2LS

This parameter is mandatory.

Indicates mapping from JSON to the language structure.

MAPPING-OVERRIDES={UNDERSCORES-AS-HYPHENS|LESS-DUP-NAMES}

Specifies whether the default behavior is overridden for the specified mapping level when the assistant generates language structures.

LESS-DUP-NAMES

This parameter generates non-structural structure field names with _value at the end of the name to enable direct referencing to the field. For example, in the following PL/I language structure, when MAPPING-OVERRIDES=LESS-DUP-NAMES is specified, level 12 field streetName is suffixed with _value:

09 streetName,                                                                                                             
    12 streetName                     CHAR(255) VARYING
   UNALIGNED,                                                                                                              
    12 filler                         BIT (7),                                                                             
    12 attr_nil_streetName_value      BIT (1),

The resulting structure is as follows:

09 streetName,                                                                                                             
    12 streetName_value               CHAR(255) VARYING
   UNALIGNED,                                                                                                              
    12 filler                         BIT (7),                                                                             
    12 attr_nil_streetName_value      BIT (1),

UNDERSCORES-AS-HYPHENS

For COBOL only. This parameter converts any underscores in the JSON Schema to hyphens, rather than the character X, to improve the readability of the generated COBOL language structures. If any field name clashes occur, the fields are numbered to ensure that they are unique. For more information, see JSON Schema to COBOL mapping.

NAME-TRUNCATION={RIGHT|LEFT}

Specifies whether JSON names are truncated from the left or the right. The web services assistant truncates JSON names to the appropriate length for the high-level language specified; by default names are truncated from the right.

PARAMETERS=filename

This is an optional parameter, which can be used to specify the assistant parameters in a separate file, rather than inline in the JCL. The file name can be an MVS PDS member, sequential data set, or a UNIX System Services file. For MVS PDS members and sequential data sets, the value must start with //. Data set names that are not enclosed in single quotation marks are automatically prefixed with the current user ID.

PDSLIB=value

Specifies the name of the partitioned data set that contains the generated high-level language. The data set members that are used for the request and response are specified in the PDSMEM parameter.

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.

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 a CICS PROGRAM resource.

When CTGJS2R is used to generate a web service binding file that is used in a service provider, you must supply this parameter. It specifies the resource name of the application program that is exposed as a web service.

STRUCTURE=data

For C and C++ only, specifies how the name of the structure is generated.

The generated structure is given the name of name01.

If the name is omitted, the structure has the same name as the partitioned data set member generated from the LS_RESTFUL parameter that you specify.

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 and CICS TG is not configured to obtain a user ID from the External Security Manager (ESM).

If you specify USERID you must also specify URI.

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

WIDE-COMP3=YES|NO

For COBOL only. Controls the maximum size of the packed decimal variable length in the COBOL language structure.

NO

JSON web services assistant limits the packed decimal variable length to 18 when it generates the COBOL language structure type COMP-3. If the packed decimal size is greater than 18, message DFHPI9022W is issued to indicate that the specified type is being restricted to a total of 18 digits.

YES

JSON web services assistant supports the maximum size of 31 when it generates the COBOL language structure type COMP-3.

WSBIND=value

The fully qualified IBM z/OS UNIX name 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 defaults to .wsbind.

Other information

• The user ID used by CTGJS2R must be configured to use UNIX System Services. The user ID must have read permission to:
  • the CICS TG for IBM z/OS UNIX file structure and PDS libraries
  • the directories that are specified on the JSON Schema parameter
  and write permission to:
  • the MVS PDS member, sequential data set, or UNIX System Services file that is specified on the language structure parameter
  • the directories that are specified on the LOGFILE, WSBIND, and WSDL parameters
• The user ID must have a sufficiently large storage allocation to run Java.

Example

//CTGJS2R JOB (0),MSGCLASS=X,CLASS=A,NOTIFY=&SYSUID,REGION=500M 
//ASSIST   EXEC PGM=BPXBATCH 
//STDPARM  DD * PGM /java/java71_64/J7.1_64/bin/java 
-Xmx230M 
-Xshareclasses:name=ctgAssistant910,nonfatal,groupAccess 
-jar /usr/lpp/cicstg/ctg910/classes/ctgassistant.jar 
LANG=Cobol 
MAPPING-MODE=JS2LS 
JSON_SCHEMA-RESTFUL=/u/userid/schema/restful.json 
LS-RESTFUL=//'USERID.PROJECT.COBOL(RESTFUL)' 
WSBIND=/u/userid/wsbind/program.wsbind 
PGMNAME=PROGRAM PGMINT=CHANNEL 
/* 
//STDOUT   DD SYSOUT=* 
//STDERR   DD SYSOUT=* 
//