The DFHLS2WS procedure generates a Web service description
and a Web service binding file from a high-level language data structure.
You can use DFHLS2WS when you expose a CICS® application
program as a service provider.
As per the W3C recommendation for WSDL documents, DFHLS2WS
uses a top level wrapper element to contain the body of the SOAP message.
The wrapper element takes the name of the WSDL operation and is represented
as a complexType in the WSDL document.
The
job control statements for DFHLS2WS, its symbolic parameters, its
input parameters and their descriptions, and an example job help you
to use this procedure.
Job control statements for DFHLS2WS
- JOB
- Initiates the job.
- EXEC
- Specifies the procedure name (DFHLS2WS).
DFHLS2WS requires sufficient
storage to run a Java™ virtual machine (JVM). You
are advised to specify REGION=0M on the EXEC
statement.
- INPUT.SYSUT1 DD
- Specifies the input. The input parameters are usually specified
in the input stream. However, they can be defined in a data set, or
in a member of a partitioned data set.
The temporary work space
DFHLS2WS
creates the following three temporary files during execution:
- tmpdir/tmpprefix.in
- tmpdir/tmpprefix.out
- tmpdir/tmpprefix.err
where
- tmpdir is the value specified
in the TMPDIR parameter
- tmpprefix is the value specified
in the TMPFILE parameter.
The default names for the files (when
TMPDIR and
TMPFILE are
not specified), are:
- /tmp/LS2WS.in
- /tmp/LS2WS.out
- /tmp/LS2WS.err
Important: DFHLS2WS does not lock access to the
generated HFS file names. Therefore, if two or more instances of DFHLS2WS
run concurrently, and use the same temporary workspace files, there
is nothing to prevent one job overwriting the workspace files while
another job is using them. This can lead to unpredictable failures.
Therefore,
you are advised to devise a naming convention, and operating procedures,
that will avoid this situation. For example, you can use the system
symbolic parameter SYSUID to generate workspace file names that are
unique to an individual user.
These temporary files are deleted
before the end of the job.
Input parameters for DFHLS2WS
If
you need any help understanding this syntax diagram, see Syntax notation.

>>-PDSLIB=value--+-------------+--+--------------+-------------->
'-PDSCP=value-' '-REQMEM=value-'
>--+---------------+-------------------------------------------->
'-RESPMEM=value-'
>--+-+-LANG=COBOL----------+--------------------------------------------+-->
| +-LANG=PLI-ENTERPRISE-+ |
| '-LANG=PLI-OTHER------' |
'-+-LANG=C---+--+--------------------------------------------------+-'
'-LANG=CPP-' | .-DFHREQUEST--. .-DFHRESPONSE--. |
'-STRUCTURE=(-+-+---------+-+-,-+-+----------+-+-)-'
'-request-' '-response-'
.-PGMINT=CHANNEL--+--------------+-.
| '-CONTID=value-' |
>--PGMNAME=value--+------------------+--+-----------+--+-----------+--+----------------------------------+-->
'-TRANSACTION=name-' '-USERID=id-' '-URI=value-' '-PGMINT=COMMAREA------------------'
>--WSBIND=value--WSDL=value--LOGFILE=value---------------------->
.-MAPPING-LEVEL=1.0------------------------.
>--+------------------------------------------+----------------->
+-MAPPING-LEVEL=1.1------------------------+
| .-CHAR-VARYING=NO---. |
'-MAPPING-LEVEL=1.2--+-------------------+-'
'-CHAR-VARYING=NULL-'
.-MINIMUM-RUNTIME-LEVEL=MINIMUM-.
>--+-------------------------------+--+-------------+----------->
+-MINIMUM-RUNTIME-LEVEL=1.0-----+ '-CCSID=value-'
+-MINIMUM-RUNTIME-LEVEL=1.1-----+
+-MINIMUM-RUNTIME-LEVEL=1.2-----+
'-MINIMUM-RUNTIME-LEVEL=CURRENT-'
>--+-------------------------+--+--------------------------+---->
'-REQUEST-NAMESPACE=value-' '-RESPONSE-NAMESPACE=value-'
>--+----------------------+--+--------------+------------------><
| .-NO-. | +-WSDLCP=LOCAL-+
+-SYNCONRETURN=-+----+-+ '-WSDLCP=UTF-8-'
'-SYNCONRETURN=YES-----'
Parameter use
- You can specify the input parameters in any order.
- Each parameter must start on a new line.
A parameter (and its continuation character, if you use
one) must not extend beyond column 72; columns 73 to 80 should contain
blanks.
- If a parameter is too long to fit on a single line, use an asterisk
(*) character at the end of the line to indicate that the parameter
continues on the next line. Everything (including spaces) before the
asterisk is considered part of the parameter. For example:
WSBIND=wsbinddir*
/app1
is equivalent toWSBIND=wsbinddir/app1
- A # character in the first character position of the line is a
comment character. The line is ignored.
Parameter descriptions
CCSID=value
Specifies the CCSID that is used at run time to encode character
data in the application data structure. The value of this parameter
overrides the value of the LOCALCCSID system
initialization parameter. The value must be an
EBCDIC CCSID that is supported by Java and z/OS conversion services.
If you do not specify this parameter, the application data structure
is encoded using the CCSID specified in the system initialization
parameter. You can use this parameter with any mapping level. However,
if you want to deploy the generated files, you must apply APAR PK23547
to the CICS region to achieve the minimum runtime level of code to
install the Web service binding file.

CHAR-VARYING=NO|NULL
Specifies how character fields in the language structure should
be mapped when the mapping level is 1.2. 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. This parameter does
not apply to Enterprise and Other PL/I language structures. The options
you can select are:- NO
- Character fields are mapped to an xsd:string and
are processed as fixed length fields. The maximum length of the data
is equal to the length of the field.
- NULL
- Character fields are mapped to an xsd:string and
are processed as null terminated strings. CICS adds a terminating
null character when transforming from a SOAP message. The maximum
length of the character string is calculated as one character less
than the length indicated in the language structure.

- CONTID=value
- In a service provider, specifies the name of the container that
holds the top level data structure used to represent a SOAP message.
The length of the container
that CICS passes to the target application program is the greater
of the lengths of the request container and the response container.
- 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 HFS name of the file into which DFHLS2WS writes
its activity log and trace information. DFHLS2WS creates the file
(but not the directory structure) if it does not already exist.
Normally,
you will not need to use this file, but it may be requested by the IBM service
organization if you encounter problems with DFHLS2WS.
MAPPING-LEVEL={1.0|1.1|1.2}
Specifies the level of mapping that DFHLS2WS should use when generating
the Web service binding file and Web service description. This parameter
is available when you apply APAR PK15904. You also need to apply APAR
PK23547 if you want to use the 1.2 mapping level option. The options
you can select are:- 1.0
- This is the default mapping level.
- 1.1
- Use this mapping if you need to regenerate a binding file at this
specific level.
- 1.2
- At this mapping level you can use the parameter CHAR-VARYING to
control how character arrays should be processed at run time. VARYING
and VARYINGZ arrays are also supported in PL/I.
For details of what is supported at each level of mapping,
see Mapping levels for the CICS Web services assistant.
MINIMUM-RUNTIME-LEVEL={MINIMUM|1.0|1.1|1.2|CURRENT}
Specifies the minimum CICS runtime environment that the Web service
binding file can be deployed into. If you select a level that does
not match the other parameters that you have specified, you receive
an error message. The options you can select are:- MINIMUM
- The lowest possible runtime level of CICS is allocated automatically
given the parameters that you have specified.
- 1.0
- The generated Web service binding file deploys successfully into
a CICS TS 3.1 region
that does not have APARs PK15904 and PK23547 applied. You cannot specify
the CHAR-VARYING, CCSID,
or MAPPING-LEVEL parameters.
- 1.1
- The generated Web service binding file deploys successfully into
a CICS TS 3.1 region
that has at least APAR PK15904 applied. You cannot specify the CHAR-VARYING or CCSID parameters.
You cannot use a mapping level of 1.2 for the MAPPING-LEVEL parameter.
- 1.2
- The generated Web service binding file deploys successfully into
a CICS TS 3.1 region
that has both APAR PK15904 and PK23547 applied. You can use any optional
parameter at this level.
- CURRENT
- The generated Web service binding file deploys successfully into
a CICS region at the same runtime level as the one you are using to
generate the Web service binding file.

- PDSLIB=value
- Specifies the name of the partitioned data set that contains the
high level language data structures to be processed. The data set
members used for the request and response are specified in the REQMEM and RESPMEM parameters
respectively.
Restriction: The records in the partitioned
data set must have a fixed length of 80 bytes.
PDSCP=value
Specifies the code page used in the partitioned data set members
specified in the REQMEM and RESPMEM parameters, where value is
a CCSID number or a Java code page number. If this parameter is not
specified, then the z/OS® UNIX System
Services code page is used. For example, you could specify PDSCP=037.
- PGMINT=CHANNEL|COMMAREA
- For a service provider, specifies how CICS passes
data to the target application program:
- CHANNEL
- CICS uses a channel interface to pass data to
the target application program.
- COMMAREA
- CICS uses a communication area to pass data
to the target application program.
This parameter is ignored when the output from DFHLS2WS
is used in a service requester.
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 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 target CICS application
program that will be exposed as a Web service. This is the program
that the CICS Web service support will link to.
- REQMEM=value
- Specifies the name of the partitioned data set member which contains
the high level language structure for the Web service request:
- For a service provider, the Web service request is the input to
the application program
- For a service requester, the Web service request is the output
from the application program
- REQUEST-NAMESPACE=value
- Specifies the namespace of the XML schema for the request message
in the generated Web service description. If you do not specify this
parameter, CICS generates a namespace automatically.
- RESPMEM=value
- Specifies the name of the partitioned data set member which contains
the high level language structure for the Web service response:
- For a service provider, the Web service response is the output
from the application program
- For a service requester, the Web service response is the input
to the application program
If there is no response (that is, for one way messages) omit
this parameter.
- RESPONSE-NAMESPACE=value
- Specifies the namespace of the XML schema for the response message
in the generated Web service description. If you do not specify this
parameter, CICS generates a namespace automatically.
- STRUCTURE=(request,response)
- For C and C++ only, specifies the names of the high level structures
contained in the partitioned data set members specified in the REQMEM
and RESPMEM parameters:
- request
- specifies the name of the high level structure containing the
request when the REQMEM parameter is specified. The default value
is DFHREQUEST.
- The partitioned data set member must contain a high level structure
with the name that you specify (or a structure named DFHREQUEST if
you do not specify a name).
- response
- specifies the name of the high level structure containing the
response when the RESPMEM parameter is specified. The default value
is DFHRESPONSE.
- If you specify a value, the partitioned data set member 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 syncpoint. - NO
- The remote Web service cannot issue a syncpoint. This value is
the default. If the remote Web service issues a syncpoint, it fails
with an ADPL abend.
- YES
- The remote Web service can issue a syncpoint. 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.

TRANSACTION=name
In a service provider, this parameter specifies the 1-4 character
name of an alias transaction that can start the pipeline. The value
of this parameter is used to define the TRANSACTION attribute of the
URIMAP resource when it is created automatically using the PIPELINE
scan command. Acceptable characters:A-Z a-z 0-9 $ @ # _ < >
|

- URI=value
- In a service provider, this parameter specifies the relative URI
that a client will to use to access the Web service. CICS uses
the value specified when it generates a URIMAP resource from the Web
service binding file created by DFHLS2WS: the parameter specifies
the path component of the URI to which the URIMAP definition applies.
USERID=id
In a service provider, this parameter specifies a 1-8 character
user ID which can be used by any Web client. For an application-generated
response or a Web service, the alias transaction is attached under
this user ID. The value of this parameter is used to define the USERID
attribute of the URIMAP resource when it is created automatically
using the PIPELINE scan command.Acceptable characters:A-Z a-z 0-9 $ @ #
|

- WSBIND=value
- The fully qualified HFS name of the Web service binding
file. DFHLS2WS creates the file (but not the directory structure)
if it does not already exist.
- WSDL=value
- The fully qualified HFS name of the file into which the Web service
description is written. DFHLS2WS creates the file (but not the directory
structure) if it does not already exist.
WSDLCP=LOCAL|UTF-8
Specifies the code page that is used to generate the WSDL document. - LOCAL
- This value specifies that the WSDL document is generated using
the local code page and no encoding tag is generated in the WSDL document.
- UTF-8
- This value specifies that the WSDL document is generated using
the UTF-8 code page. An encoding tag is generated in the WSDL document.
If you specify this option, you must ensure that the encoding remains
correct when copying the WSDL document between different platforms.

Other information
- The user ID under which DFHLS2WS runs must be defined to OMVS.
The user ID must have read permission to the CICS HFS
file structure and PDS libraries, and write permission to the directories
specified on the LOGFILE, WSBIND,
and WSDL parameters.
- The user ID must have a sufficiently large storage allocation
to run Java.
Example
//LS2WS JOB 'accounting information',name,MSGCLASS=A
// SET QT=''''
//JAVAPROG EXEC DFHLS2WS,
// TMPFILE=&QT.&SYSUID.&QT
//INPUT.SYSUT1 DD *
PDSLIB=//CICSHLQ.SDFHSAMP
REQMEM=DFH0XCP4
RESPMEM=DFH0XCP4
LANG=COBOL
LOGFILE=/u/exampleapp/wsbind/inquireSingle.log
MAPPING-LEVEL=1.0
PGMNAME=DFH0XCMN
URI=exampleApp/inquireSingle
PGMINT=COMMAREA
WSBIND=/u/exampleapp/wsbind/inquireSingle.wsbind
WSDL=/u/exampleapp/wsdl/inquireSingle.wsdl
WSDLCP=LOCAL
/*