DFHLS2WS: high level language to WSDL conversion

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.

Symbolic parameters

The following symbolic parameters are defined in cataloged procedure DFHLS2WS:
JAVADIR=path
Specifies the name of the Java directory that is used by DFHLS2WS. The value of this parameter is appended to /usr/lpp/ giving a complete path name of /usr/lpp/path.
Normally, you do not need to specify this parameter; the default value is the value that was supplied to the CICS installation job (DFHISTAR) in the JAVADIR parameter.
Start of changePATHPREF=prefixEnd of change
Start of changeSpecifies an optional prefix that extends the HFS directory path used on other parameters. The default is the empty string.End of change
Start of changeNormally, you do not need to specify this parameter; the default value is the value that was supplied to the CICS installation job (DFHISTAR) in the JAVADIR parameter.End of change
Start of changeSERVICE=valueEnd of change
Start of changeUse this parameter only when directed to do so by IBM® support.End of change
TMPDIR=tmpdir
Specifies the location of a directory in HFS that DFHLS2WS uses as a temporary work space. The user ID under which the job runs must have read and write permission to this directory.
The default value is /tmp.
TMPFILE=tmpprefix
Specifies a prefix that DFHLS2WS uses to construct the names of the temporary workspace files.
The default value is LS2WS
USSDIR=path
Specifies the name of the CICS TS directory in the UNIX system services HFS. The value of this parameter is appended to /usr/lpp/cicsts/ giving a complete path name of /usr/lpp/cicsts/path
Normally, you do not need to specify this parameter; the default value is the value that was supplied to the CICS installation job (DFHISTAR) in the USSDIR parameter.

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.

Read syntax diagramSkip visual syntax diagram
>>-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

Parameter descriptions

Start of changeCCSID=valueEnd of change
Start of changeSpecifies 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.

End of change
Start of changeCHAR-VARYING=NO|NULLEnd of change
Start of changeSpecifies 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.
End of change
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.

Start of changeThe 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.End of change

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.
Start of changeLANG=PLI-OTHEREnd of change
Start of changeSpecifies that the programming language of the high level language structure is a level of PL/I other than Enterprise PL/I.End of change
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.

Start of changeMAPPING-LEVEL={1.0|1.1|1.2}End of change
Start of changeSpecifies 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.End of change
Start of changeMINIMUM-RUNTIME-LEVEL={MINIMUM|1.0|1.1|1.2|CURRENT}End of change
Start of changeSpecifies 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.
End of change
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.
Start of changePDSCP=valueEnd of change
Start of changeSpecifies 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.End of change
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.

Start of changeWhen 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.End of change

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).
Start of changeSYNCONRETURN=NO|YESEnd of change
Start of changespecifies 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.
End of change
Start of changeTRANSACTION=nameEnd of change
Start of changeIn 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 $ @ # _ < >
End of change
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.
Start of changeUSERID=idEnd of change
Start of changeIn 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 $ @ #
End of change
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.
Start of changeWSDLCP=LOCAL|UTF-8End of change
Start of changeSpecifies 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.
End of change

Other information

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
Start of changeLOGFILE=/u/exampleapp/wsbind/inquireSingle.logEnd of change
Start of changeMAPPING-LEVEL=1.0End of change
PGMNAME=DFH0XCMN
URI=exampleApp/inquireSingle
PGMINT=COMMAREA
WSBIND=/u/exampleapp/wsbind/inquireSingle.wsbind
WSDL=/u/exampleapp/wsdl/inquireSingle.wsdl
Start of changeWSDLCP=LOCALEnd of change
/*