Start of change

Creating a Request-Response WSBind file from a language structure

Sample JCL called CTGLS2JS is provided to help you use the JSON web services assistant to generate a web service binding file and JSON Schemas from high-level language data structures.

You can use CTGLS2JS when you run a CICS® application program as a service provider.

The sample JCL is installed in the data set hlq.SCTGSAMP, where hlq is the high-level qualifier where CICS TG is installed.

CTGLS2JS.txt contains the required parameters for creating a Request-Response JSON web service WSBind file from high-level language structures.

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

Note: The JSON web services assistant does not lock access to the z/OS UNIX System Services files or the data set members. Therefore, if two or more instances of JSON web services assistant run concurrently, and use the same temporary workspace files, nothing prevents one job from overwriting the workspace files while another job is using them, leading to unpredictable failures. You should devise a naming convention, and operating procedures, that avoid this situation.

Parameter use

If you continue an MVS™ PDS member or sequential data set value on a new line, ensure that the characters // do not start in column 1, to avoid a JCL error when you submit the job. For example, if you continue the LS-RESPONSE parameter across multiple lines use:
LS-RESPONSE=\
 //'USERID.PROJECT.COBOL(RESPONSE)'

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 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 UNIX System Services path and filename where the request JSON Schema is stored.
JSON-SCHEMA-RESPONSE=value
This parameter is mandatory.
The value indicates the UNIX System Services path and 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 z/OS UNIX name 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 in the partitioned data set members that are 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 z/OS UNIX System Services code page is used.
For example, LS-CODEPAGE=037.
LS-REQUEST=value
Specifies the UNIX System Services path and filename or MVS dataset or PDS member that the JSON web services assistant uses to generate the names of the partitioned data set members 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 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.

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 the MVS PDS member, sequential data set, or a UNIX System Services file that contains 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 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.

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.
PARAMETERS=filename
This is an optional parameter, which can be used to specify the assistant parameters in a separate file, instead of 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.
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 partitioned data set members 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 MVS PDS member, sequential data set, or UNIX System Services file that is specified on the LS-REQUEST parameter must contain a high-level structure with the name that you specify or a structure that is named DFHREQUEST 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 MVS PDS member, sequential data set, or a UNIX System Services file that is specified on the LS-RESPONSE parameter must contain a high-level structure with the name that you specify or a structure named DFHRESPONSE 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|HP-UX|Solaris|IBM-i|VSE|LinuxI|Windows}
Specifies the platform for the CICS server that receives requests from this web service.
zOS
CICS Transaction Server for z/OS
AIX
TXSeries™ for Multiplatforms on AIX®
HP-UX
TXSeries for Multiplatforms on HP-UX
Solaris
TXSeries for Multiplatforms on Solaris
IBM-i
CICS Transaction Server for i
VSE
CICS Transaction Server for VSE/ESA
LinuxI
TXSeries for Multiplatforms on Intel Linux
Windows
TXSeries for Multiplatforms on Microsoft Windows
For z/OS, data is aligned on the 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).
Acceptable characters:

A-Z a-z 0-9 $ @ #

If you specify USERID you must also specify URI.
WSBIND=value
The fully qualified 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 is .wsbind.

Other information

Example

//CTGLS2JS 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=LS2JS 
JSON_SCHEMA-REQUEST=/u/userid/schema/request.json 
JSON_SCHEMA-RESPONSE=/u/userid/schema/response.json 
LS-REQUEST=//'USERID.PROJECT.COBOL(REQUEST)' 
LS-RESPONSE=//'USERID.PROJECT.COBOL(RESPONSE)' 
WSBIND=/u/userid/wsbind/program.wsbind 
PGMNAME=PROGRAM 
PGMINT=CHANNEL 
/* 
//STDOUT   DD SYSOUT=* 
//STDERR   DD SYSOUT=* 
//

Reference Reference

Feedback


Timestamp icon Last updated: Wednesday, 27 August 2014


https://ut-ilnx-r4.hursley.ibm.com/tgzos_latest/help/topic/com.ibm.cics.tg.zos.doc//progguide/topics/ls2js.html
End of change