SOAP Clients

SOAP is one method for accessing the
CA Endevor
API
ce18
Web Services supports two methods for accessing the
CA Endevor
API. The SOAP method is built using the Axis2 framework. This method supports most of the
CA Endevor
actions.The actions supported by SOAP are listed under the "Category" parameter of the SCL object in this article.
The other method is RESTful API. For more information on RESTful API, see "Using the REST API".
3
CA Endevor
SOAP Web Services
The SOAP client design model requires a client-side stub. The web developer must create a client stub from the
CA Endevor
Web Services WSDL (Web Services Description Language) file. WSDL is a service description protocol. The WSDL file is a dynamic XML file that serves as the interface between a client program and the web service. The Web Service WSDL file describes what
CA Endevor
operations are available to the client program and the SOAP protocol bindings and message formats required to enable the client to interact with Web Services.
The client stub is responsible for conversion of parameters used in a function call and deconversion of the results passed from the server after execution of the function. The client stub interacts with the web service stub.
The program developer writes the client program to collect the following information:
  • A login user ID and password for access to a specified
    CA Endevor
    repository
  • An SCL statement with optional wsParameters
  • If this is a submitSCL request, then parameters for a SOAP Attachment to transport data to and from Web Services are also required
Depending on the programming language of the client program, details for generating the client stub can differ, but conceptually the process is very similar. A stub generator is used to produce a stub for a programming language. Then the stub is included in the source code.
  • For client programs written in C, the stub, in C code, is compiled and the generated header files are required to code the application program. The application program must have the #include structure.h in C++ include wobject.h>
  • For client programs written in Java, the stub is a collection of Java sources grouped in a package. The sources are compiled by the javac compiler into a JAR file. This JAR file is required by the sample code. The program code must include an import statement that refers to the generated packages (this allows the java IDE to make the Loginproperties object available to the application program). The client program can instantiate the stub to invoke the web service. For a client to access the stub, the stub class should be present in the classpath of the client application.
    A Java client program instantiates the following objects and populates them with the correct values for a specific request.
    • LoginProperties
    • SCL
    • Attachment
    The client stub created from the Web Services WSDL supports the instantiation of these objects. The data in these objects is required by Web Services. The client program populates the objects with the required parameters.
How to Create a Client Stub
The SOAP client design model requires a client stub to enable the client program to access Web Services. The client application developer must create a client stub, using the Web Services WSDL file. Then the client-side stub must be incorporated as an import package into the client program. The stub manages, sends, and receives SOAP messages to communicate with the web service.
  • You can create the client stub manually or using a utility. After Web Services is installed, the WSDL file can be accessed using a web browser and saved as an xml file. There are third-party tools, for example, WSDL2Java (part of the Axis2 distributions) that can be used to generate a client-side stub from the WSDL.
    The WSDL file for Web Services is located at:
    http://
    servername
    :
    portnumber
    /EndevorService/services/EndevorService?wsdl
    Replace the
    servername
    :
    portnumber
    specifications with the name and port number of the web server where your installation of Web Services resides.
  • After the stub is written or generated, the client stub has to be compiled and the client application's logic implemented above the stub.
    The client program must instantiate the stub to invoke the web service. For a client to access the stub, the stub class needs to be present in the classpath of the client application.
Java Client Program Objects and Parameters
A Java client program populates the objects with the following required parameters:
  • LoginProperties object
    - Contains the following parameters:
    • DataSource
      Specifies the data source repository (
      CA Endevor
      ) that the client wants to access. This value must match the name of a valid configuration file accessible by Web Services. For more information, see "Configuration Files".
    • UserID
      Specifies the user ID for access to the
      CA Endevor
      API.
    • Password
      Specifies the password for access to the
      CA Endevor
      API.
  • SCL object
    - Contains the following parameters:
    • Statement
      Specifies the SCL statement entered by the user of the client application.
      For any get
      Object
      service request, a Comma-Separated Value utility List statement is required. For more information about List statements, see "Comma-Separated Value (CSV) Reporting Utility".
    • wsParameters
      (Optional) Specifies parameters and values to override wsParameters that are specified in the configuration file. These parameters are Lang, TimeZone, CodePage, LSF.Encoding, Encoding, CharacterSet, ContentType, Trace, and Tracer. For more information, see "Configuration File Parameters".
    • Category
      Specifies the type of SCL request.
      All
      the SCL specified in a request must be for the same type. Valid values follow:
      • A
        Specifies Environment administration actions (Batch Admin).
      • C
        Specifies Comma Separated Value (CSV) utility actions. Required for any get
        Object
        service request.
      • E
        Specifies Element actions, except those named in category L.
      • P
        Specifies Package actions.
      • S
        Specifies Package Ship actions.
      • X
        Specifies batch ACM Query utility actions.
      • L
        Specifies Add, Update, or Retrieve Element actions that require local file system (LFS) support. The SCL statements for these actions require the TO | FROm ATTachment PATH LFSFILE clause in order to transfer data to or from the local client.
        Use Category E for Add, Update, and Retrieve Element actions that are not LFS requests. That is, when those Element actions use the TO | FROm DSName or TO | FROm PATH USSFILE clause.
    • Timezone
      Specifies the timezone where the client application is located. Web Services uses this value to determine the correct time, on the client side, for use in messages.
  • Attachments object
    - Contains the following parameters:
    • DD
      Specifies the data set on the client side that contains the data being exchanged.
      For the base64Binary type, the DATA are coded with the 64Binary translation and manipulated by a data handler or without any translation and appended as a MTOM attachment. The client code is expected to fill the DD property using a data handler (in the case of the 64binary translation) or as MTOM attachment to take advantage of the streaming.
    • DDName
      Specifies the attachment name that references what is being exchanged.
    • contentType
      Specifies the data type being exchanged. Specifies how the data transported by the Attachment objects of the client call are coded. This value informs Web Services how to format the data part of the attachment. ContentType is a standard of the Multipurpose Internet Mail Extensions (MIME) message protocol used by HTTP for complex messages, including messages with file attachments.
Example: Client Program in Java for the SubmitSCL Service
A Java client program invokes a stub (generated from the WSDL) and runtime (AXIS2/Java). The following sample program for the submitSCL service instantiates the loginProperties object, the SCL object, and the Attachments object. The client program populates the objects with the values required for a specific client request.
The request includes the login properties for access to a specified
CA Endevor
repository. The request also includes the SCL statement and optional parameters, and a SOAP Attachment, used to submit an SCL statement and data to Web Services.
public void consume() { setException (null) ; int attachmentCount = 0; /* * instantiate the logirProperties object */ loginProperties loginProperties = new LoginProperties () ; loginProperties.setDataSource(this.getDataSource ()) ; loginProperties.setUserId(this.getUserID ()) ; loginProperties.setPassword(this.getPassword ()) ; /* * instantiate the SCL object */ SCL scl = new SCL(); scl.setStatement(this.getStatement ()) ; scl.setUsParameters(this.getUsParameters ()) ; /* * instantiate the Attachments object */ if (inputAttachments != null) for (int attachmentNumber = 0; attachmentNumber < inputAttachments.length; attachmentNumber++) { Attachments attachment = new Attachments () ; attachment.setDDName(inputAttachments[attachmentNumber] .getDDName ()) ; attachment.setContentType(inputAttachments[attachmentNumber] .getContentType ()) ; FileDataSource dataSource = new FileDataSource( inputAttachments[attachmentNumber].getInputFileName ()) ; DataHandler dataHandler = new DataHandler (dataSource) ; attachment.setDD (DataHandler) ; scl.addAttachments (attachment) ; } SubmitSCL submitSCL = new SubmitSCL () ; submitSCL.setLoginProperties (loginProperties) ; submitSCL.setScl (scl) ; }
Valid Operations for User-Written Client Programs
User-written programs use Web Services to send Software Control Language (SCL) statements (with some restrictions) to the
CA Endevor
API. In addition, information can be retrieved from Master Control File, Package File, and repository objects. For more information, see SubmitSCL Operation and Get<Object> Operation.
SubmitSCL Operation
Web Services supports the submitSCL operation. Client requests can communicate with the
CA Endevor
API using the
CA Endevor
Software Control Language (SCL). With some restrictions, any valid SCL statement can be sent to the
CA Endevor
API and the results are returned to the client, providing full access to the repository.
Valid SCL statements for the submitSCL operation for Web Services are subject to certain restrictions.
  • The following actions are
    not
    valid:
    • &&ACTION
    • Archive element
    • Copy element
    • List member From Archive
    • Print member From Archive
    • Restore element
    • Transfer To Archive
    • Transfer From Archive
    • Archive Package
    • Export Package
  • The parameter DDNAME is
    not
    supported for Web Services. However, DDNAME C1PRINT
    is
    valid on List and Print actions.
    The DSName
    dataset-name
    parameter
    is
    supported. Instead of the DDName parameter, the Add, Update, and Retrieve actions use SOAP attachments to transport data between the client and the mainframe. For more information, see TO | FROm ATTachment Clause on SCL Statement.
No footprint information is stored in files retrieved from
CA Endevor
. Temporary files written to the Web Services server are purged at the start of each new local file system command.
TO | FROm ATTachment Clause on SCL Statement
Every web service call (request) from a client application requires a SOAP Attachment object to submit requests and receive responses. If the request transports data between the client and Web Services, the SCL statement must include a From Attachment or To Attachment clause. This clause specifies the name and location of the file on the client side that is being sent from the client or to the client.
The following SCL requests support the From Attachment clause:
  • Element actions Add or Update.
  • Upload of package SCL statements.
The following SCL requests support the To Attachment clause:
  • Element action Retrieve.
  • Fetch of reports.
  • Extract of Comma Separated Value (CSV) data.
TO | FROm ATTachment Syntax
Category L
Instead of the TO | FROm DDNAME clause on the SCL statement for an Add, Update, or Retrieve action, use this syntax:
TO|FROm ATTachment
attachment-name
PATH
mypath
LFSFILE
myfile
  • TO ATTachment
    attachment-name
    Specifies the name of the SOAP Attachment object that contains the data that is to be sent from
    CA Endevor
    to the client.
  • FROm ATTachment
    attachment-name
    Specifies the name of the SOAP Attachment object that contains the data that is to be sent from the client to
    CA Endevor
    .
  • PATH
    mypath
    Specifies the directory on the client side. For the From Attachment clause, Path is where the source file resides. For the To Attachment clause, Path is where the file is to be saved to.
  • LFSFILE
    myfile
    Specifies the name of the file in the directory on the client side. For the From Attachment clause, Lfsfile is the name of the source file. For the To Attachment clause, Lfsfile is the name that the received file is saved as.
Categories E, P, and C
Instead of the TO | FROm DDNAME clause on the SCL statement, use this syntax:
TO|FROm ATTachment
attachment-name
  • TO ATTachment
    attachment-name
    Specifies the name of the SOAP Attachment object that contains the data that is to be sent from
    CA Endevor
    to the client.
  • FROm ATTachment
    attachment-name
    Specifies the name of the SOAP Attachment object that contains the data that is to be sent from the client to
    CA Endevor
    .
Example: Add Element Statement with Attachment
The following Add Element statement adds element CCIDRPT2 to Stage 1 of the DEV Environment, EABASE System, UTILITY Subsytem, COBOL Type library. The SOAP Attachment object UPLOADD contains a copy of the content of
myfile
located at
mypath.
on the client side. This statement adds the contents of the SOAP Attachment to. The optional Options clause associates the comment "Project myfile' with the Element.
ADD ELEMENT CCIDRPT2 FROM ATTACHMENT UPLOADDD PATH
mypath
LFSFILE
myfile
TO ENV DEV SYS EABASE SUB UTILITY TYPE COBOL STAGE NUMBER 1 OPTIONS UPD COMMENT '
Project myfile
'.
Example: Retrieve Element Statement with Attachment
The following Retrieve Element statement retrieves element CCIDRPT5 from Stage 1 of the DEV Environment, EABASE System, UTILITY Subsytem, COBOL Type library. A copy of the data that is element CCIDRPT5 is added to the SOAP Attachment object DNLOADD. Web Services send a SOAP message response back to the client. The SOAP message includes Attachment. The client extracts the data from the Attachment and copies it to
myfile
located at
mypath.
on the client side.
RETRIEVE ELEMENT CCIDRPT5 FROM ENV DEV SYS EABASE SUB UTILITY TYPE COBOL STAGE NUMBER 1 TO ATTACHMENT DNLOADDD PATH mypath LFSFILE myfile.
Example: Define Package Statement with Attachment
The following Define Package statement defines the package YSB, and gives YSB the description YSB-PACKAGE. The SCL is imported from attachment PKGSCL, which must be included in the request as a SOAP Attachment object.
DEFINE PACKAGE 'YSB' DESCRIPTION 'YSB-PACKAGE' IMPORT SCL FROM ATTACHMENT 'PKGSCL' OPTIONS STANDARD PACKAGE SHARABLE BACKOUT IS ENABLED.
Get<Object> Operation
Web Services supports various get<Object> services that extract information in the form of an object. Information can be acquired from the Master Control File, Package File, or repository objects. The get<Object> service is based on CSV LIST requests and makes use of a native SOAP facility for creating objects to send and decoding the CSV output that is returned.
The get<Object> services are designed like the submitSCL service. Each get<Object> service retrieves a specific type of information. The <Object> part of the service name indicates the type of information that the service can retrieve. Each get<Object> service requires a corresponding SCL statement that has been appropriately coded to extract the requested information. Each get<Object> service returns an object designed from the information extracted by the Comma Separated Value (CSV) utility as directed by the SCL statement. The extracted information is converted into XML format and returned to the client.
In terms of object-oriented programming, the get<Object> service returns an array, designated as Object[]. Each entry in this array includes one occurrence of the retrieved objects and the object contains the requested information.
To view the property names that can be returned for each get<Object
>
service, see the WSDL file. The <Object> are built from the CSV representation, their properties map with the CSV layout. The property names match one by one with the CSV columns as described by the WSDL file.
The returned property names and values are the same as those returned by the CSV utility. However, in the case of an object (rather than a CSV request output) the properties are typed as string, integer, or date. The WSDL defines the type of each property. The date and timestamp is the external representation of the
CA Endevor
stamp-coded using the z/OS time zone.
For more information about the Web Services component, see How to Enable Web Services.
Get<Object> Syntax for SCL Statements
Each get<Object> service requires a specific type of SCL statement. These SCL statements are the same as those used by the CSV utility. If a service request includes an incorrect SCL statement or an SCL statement that does not correspond to the get<Object>, the request is rejected. For more information, see List Subsystem function.
The following get<Object
>
services are supported. The minimum required SCL syntax is shown next with each operation.
  • getApproverGroup
    LISt APProver GROup
    approver-group-name
  • getApproverGroupJunction
    LISt APProve GROut JUNction FROm
    options
  • getConfiguration
    LISt CONFIguration
  • getConfigurations
    LISt CONFigurations
  • getDataSet
    LISt DSName FROm
    options
  • getDestination
    LISt DEStination
    destination-id
  • getElementBasic
    LISt ELEment
    element-name
    FROm
    options
    DATa BASic
  • getElementDetail
    LISt ELEment
    element-name
    FROm
    options
    DATa ALL
  • getElementSummary
    LISt ELEment element-name FROm
    options
    DATa SUMmary
  • getEnvironment
    LISt ENVironment
    environment-name
  • getPackage
    LISt PACkage
    package-id
  • getPackageActionSummary
    LISt PACkage ACTion FROm PACkage
    package-id
  • getPackageApproverGroup
    LISt PACkage APProver GROup FROm PACkage
    package-id
  • getPackageSCL
    LISt PACkage SCL FROm PACkage
    package-id
  • getPackageShip
    LISt PACkage SHIp FROm PACkage
    package-id
  • getProcessorGroup
    LISt PROcessor GROup
    processor-group-name
  • getSystem
    LISt SYStem
    system-name
  • getSubSystem
    LISt SUBsystem
    subsystem-name
  • getStage
    LISt STAge
    stage-id
  • getType
    LISt TYPe
    type-name
How the Get<Object> Service Works
Web Services supports various get
<Object>
services that extract an array of information. The information is returned as an object-oriented programming object representation of the CSV row extracted by the SCL statement List. To acquire this array, code a Java client program that invokes a stub (generated from the WSDL) and runtime (AXIS2/Java).
The logic and coding style of a program for the get<Object> service is similar to the submitSCL() service. The program includes the following:
  • The initialization of the loginProperties object and the SCL object, populated with improvised information
  • The invocation of the web service by its name
  • The fetch of the results as an array of specialized objects and attachments containing the API reports
Example: Client Program in Java for the getTypeService
This sample Java program illustrates the getType Service.
public void consume () throws Exception { setException (null) ; /* * instantiate the loginProperties object */ LoginProperties loginProperties = new LoginProperties () ; loginProperties.setDataSource (this.getDataSource ()) ; loginProperties.setUserId (this.getUserId () ) ; loginProperties.setPassword (this.getPassword ()) ; /* * instantiate the SCL object */ SCL scl = new SCL () ; scl.setStatement (getStatement ()) ; scl.setWsParameters (getWsParametersTypeC ()) ; GetType getType = new GetType () ; getType.setLoginProperties (loginProperties) ; getType.setScl (scl) ; resultType = stub.getType (loginProperties, scl) ; result = resultType.getResult () ; Type type[] = resultType.getType () ; String siteId = type[0].getSiteId () ; }