Creating a RESTful WSBind file
Sample JCL called CTGJS2R is provided to help you use the JSON web services assistant to generate high-level language data structures and a web service binding file from a JSON Schema. You can use CTGJS2R when you prepare to create a RESTful JSON service provider.
The sample JCL CTGJS2R is installed in the data set hlq.SCTGSAMP, where hlq is the high-level qualifier where CICS® TG is installed.
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.
- 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
<value>, only the
- 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
is equivalent to
//do not start in column 1, to avoid a JCL error when you submit the job. For example, if you continue the LS-RESTFUL parameter across multiple lines use:
JSON web service assistant is updated to use mapping level 4.3 compatible parameters, while generating the web service binding file
- 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
DFHCNV, then CCSID should be set to the value specified on the CLIENTCP parameter in the
- 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.
- 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:
- Variable-length character data is mapped as fixed-length strings.
- Variable-length character data is mapped to null-terminated strings.
- 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.
- 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.
- 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.
- Specifies if variable length data is tolerated in a fixed-length field structure:
- 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.
- 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.
- Specifies how JSON date-time elements are mapped to the language structure.
- The default is that any JSON date-time element is processed as a time stamp and is mapped to CICS ABSTIME format.
- The JSON date-time element is processed as text.
- 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.
- 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.
- Specifies whether inline variable repeating content is used based on the
maxItemsJSON 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
maxOccursattribute 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.
- This parameter is mandatory.
- The value specifies the UNIX System Services location where the response JSON Schema is stored.
- Specifies that the programming language of the high-level language structure is COBOL.
- Specifies that the programming language of the high-level language structure is Enterprise PL/I.
- Specifies that the programming language of the high-level language structure is a level of PL/I other than Enterprise PL/I.
- Specifies that the programming language of the high-level language structure is C.
- Specifies that the programming language of the high-level language structure is C++.
- 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
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.
- 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.
- 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.
- This parameter is mandatory.
- Indicates mapping from JSON to the language structure.
- Specifies whether the default behavior is overridden for the specified mapping level when the
assistant generates language structures.
- This parameter generates non-structural structure field names with
_valueat 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
The resulting structure is as follows:
09 streetName, 12 streetName CHAR(255) VARYING UNALIGNED, 12 filler BIT (7), 12 attr_nil_streetName_value BIT (1),
09 streetName, 12 streetName_value CHAR(255) VARYING UNALIGNED, 12 filler BIT (7), 12 attr_nil_streetName_value BIT (1),
- 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.
- 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.
- 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.
- 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.
- For a service provider, specifies how CICS TG passes data
to the target application program:
- CICS TG uses a channel interface to pass data to the target application program.
- 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.
- 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.
- For C and C++ only, specifies how the name of the structure is generated.
- The generated structure is given the name of
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.
- Specifies whether the remote web service can issue a sync point.
- 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.
- 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.
- Specifies the platform for the CICS server that receives
requests from this web service.
For IBM z/OS, data is aligned on the IBM z/OS default boundaries. For all other platforms data is aligned on natural boundaries:
- CICS Transaction Server for IBM z/OS
- IBM TXSeries® for Multiplatforms on IBM AIX®
- CICS Transaction Server for i
- CICS Transaction Server for VSE/ESA
- IBM TXSeries for Multiplatforms on Intel Linux®
- IBM TXSeries for Multiplatforms on Microsoft Windows
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
- Specifies the 1-4 character name of a transaction identifier that is passed in the
EIBTRNIDfield 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.
A-Z a-z 0-9 $ @ # _ < >
- 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.
- 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.
A-Z a-z 0-9 $ @ #
- For COBOL only. Controls the maximum size of the packed decimal variable length in the COBOL
- 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.
- JSON web services assistant supports the maximum size of 31 when it generates the COBOL language structure type COMP-3.
- 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.
- 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
- 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.
//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=* //