com.ibm.as400.data
Class ProgramCallDocument

java.lang.Object
  |
  +--com.ibm.as400.data.ProgramCallDocument
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable

public class ProgramCallDocument
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

XML Document based program call. The ProgramCallDocument class uses a Program Call Markup Language (PCML) to call AS/400 programs. PCML is an XML language for describing the input and output parameters to the AS/400 program. This class parses a PCML document and allows the application to call AS/400 programs described in the PCML document.

Command Line Interface

The command line interface may be used to serialize PCML document definitions.
 java com.ibm.as400.data.ProgramCallDocument
     -serialize
     pcml document name
 
Options:
-serialize
Parses the PCML document and creates a serialized version of the document. The name of the serialized file will match the document name, and the file extension will be .pcml.ser.

pcml document name
The fully-qualified resource name of the PCML document which defines the program interface.

See Also:
Serialized Form

Constructor Summary
ProgramCallDocument()
          Constructs a ProgramCallDocument
ProgramCallDocument(AS400 sys, java.lang.String docName)
          Constructs a ProgramCallDocument.
ProgramCallDocument(AS400 sys, java.lang.String docName, java.lang.ClassLoader loader)
          Constructs a ProgramCallDocument.
 
Method Summary
 boolean callProgram(java.lang.String name)
          Calls the named program.
 java.lang.Object clone()
          Clones the ProgramCallDocument and the objects contained in it
 Descriptor getDescriptor()
          Returns a Descriptor for the current pcml document.
static Descriptor getDescriptor(java.lang.String docName)
          Returns a Descriptor for the specified pcml document.
static Descriptor getDescriptor(java.lang.String docName, java.lang.ClassLoader loader)
          Returns a Descriptor for the specified pcml document.
 int getErrno(java.lang.String name)
          Returns an "errno" value for the named service program element.
 int getIntReturnValue(java.lang.String name)
          Returns an int return value for the named service program element.
 int getIntValue(java.lang.String name)
          Returns an int value for the named element.
 int getIntValue(java.lang.String name, int[] indices)
          Returns an int value for the named element given indices to the data element.
 AS400Message[] getMessageList(java.lang.String name)
          Returns the list of AS/400 messages returned from running the program.
 int getOutputsize(java.lang.String name)
          Returns the number of bytes reserved for output for the named element.
 int getOutputsize(java.lang.String name, int[] indices)
          Returns the number of bytes reserved for output for the named element and indices.
 java.lang.String getStringValue(java.lang.String name, int type)
          Returns a String value for the named element.
 java.lang.String getStringValue(java.lang.String name, int[] indices, int type)
          Returns a String value for the named element given indices to the data element.
 AS400 getSystem()
          Gets the AS/400 on which programs are to be called.
 boolean getThreadsafeOverride(java.lang.String program)
          Gets the value of the override of the threadsafe attribute of a program element.
 java.lang.Object getValue(java.lang.String name)
          Returns the Java object value for the named element.
 java.lang.Object getValue(java.lang.String name, int[] indices)
          Returns the Java object value for the named element given indices to the data element.
static void main(java.lang.String[] args)
          Provides a command line interface to ProgramCallDocument.
 void serialize()
          Serializes the ProgramCallDocument.
 void setDocument(java.lang.String docName)
          Sets the PCML document resource.
 void setDocument(java.lang.String docName, java.lang.ClassLoader loader)
          Sets the PCML document resource.
 void setIntValue(java.lang.String name, int value)
          Sets the Java object value for the named element using a int input.
 void setIntValue(java.lang.String name, int[] indices, int value)
          Sets the Java object value for the named element using an int input value given indices to the data element.
 void setPath(java.lang.String program, java.lang.String path)
          Allows for dynamically specifying the program path.
 void setStringValue(java.lang.String name, int[] indices, java.lang.String value, int type)
          Sets the Java object value for the named element using a String input value given indices to the data element.
 void setStringValue(java.lang.String name, java.lang.String value, int type)
          Sets the Java object value for the named element using a String input.
 void setSystem(AS400 system)
          Sets the AS/400 on which to call programs.
 void setThreadsafeOverride(java.lang.String program, boolean threadsafe)
          Allows the overriding of the threadsafe attribute of a program element.
 void setValue(java.lang.String name, int[] indices, java.lang.Object value)
          Sets the Java object value for the named element given indices to the data element.
 void setValue(java.lang.String name, java.lang.Object value)
          Sets the Java object value for the named element.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ProgramCallDocument

public ProgramCallDocument(AS400 sys,
                           java.lang.String docName)
                    throws PcmlException
Constructs a ProgramCallDocument. The PCML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for a PCML source file.
Parameters:
sys - The AS400 on which to run the program.
docName - The document resource name of the PCML document for the programs to be called. The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myPcml"
Throws:
PcmlException - when the specified PCML document cannot be found
See Also:
AS400

ProgramCallDocument

public ProgramCallDocument(AS400 sys,
                           java.lang.String docName,
                           java.lang.ClassLoader loader)
                    throws PcmlException
Constructs a ProgramCallDocument. The PCML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for a PCML source file.
Parameters:
sys - The AS400 on which to run the program.
docName - The document resource name of the PCML document for the programs to be called. The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myPcml"
loader - The ClassLoader that will be used when loading the specified document resource.
Throws:
PcmlException - when the specified PCML document cannot be found
See Also:
AS400

ProgramCallDocument

public ProgramCallDocument()
                    throws PcmlException
Constructs a ProgramCallDocument

The setSystem and setDocument methods must be called prior to using the object.

Throws:
PcmlException - when the specified PCML document cannot be found
See Also:
setSystem(com.ibm.as400.access.AS400), setDocument(java.lang.String), AS400
Method Detail

clone

public java.lang.Object clone()
Clones the ProgramCallDocument and the objects contained in it

The setSystem and setDocument methods must be called prior to using the object.

Overrides:
clone in class java.lang.Object
See Also:
setSystem(com.ibm.as400.access.AS400), setDocument(java.lang.String), AS400

main

public static void main(java.lang.String[] args)
Provides a command line interface to ProgramCallDocument. See the class description.

callProgram

public boolean callProgram(java.lang.String name)
                    throws PcmlException
Calls the named program.
Parameters:
name - The name of the <program> element in the PCML document.
Throws:
PcmlException - If an error occurs.

getErrno

public int getErrno(java.lang.String name)
             throws PcmlException
Returns an "errno" value for the named service program element.

The named program element must be defined as service program entrypoint. The value returned is the "errno" value resulting from the most recent call to the program. If the program has not been called, zero is returned.

Parameters:
name - The name of the <program> element in the PCML document.
Returns:
The integer "errno" value for the named service program element.
Throws:
PcmlException - If an error occurs.

getDescriptor

public static Descriptor getDescriptor(java.lang.String docName)
                                throws PcmlException
Returns a Descriptor for the specified pcml document. The PCML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for a PCML source file.
Parameters:
docName - The document resource name of the PCML document for which the Descriptor is returned. The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myPcml"
Returns:
The Descriptor for the pcml element of the named pcml file.
Throws:
PcmlException - when the specified PCML document cannot be found
See Also:
Descriptor

getDescriptor

public static Descriptor getDescriptor(java.lang.String docName,
                                       java.lang.ClassLoader loader)
                                throws PcmlException
Returns a Descriptor for the specified pcml document. The PCML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for a PCML source file.
Parameters:
docName - The document resource name of the PCML document for which the Descriptor is returned. The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myPcml"
loader - The ClassLoader that will be used when loading the specified document resource.
Returns:
The Descriptor for the pcml element of the named pcml file.
Throws:
PcmlException - when the specified PCML document cannot be found
See Also:
Descriptor

getDescriptor

public Descriptor getDescriptor()
Returns a Descriptor for the current pcml document.
Returns:
The Descriptor for the pcml element of the current pcml file or null if the pcml document has not be set.
See Also:
Descriptor

getIntReturnValue

public int getIntReturnValue(java.lang.String name)
                      throws PcmlException
Returns an int return value for the named service program element.

The named program element must be defined as service program entrypoint. The value returned is the integer return value from the most recent call to the program. If the program has not been called, zero is returned.

Parameters:
name - The name of the <program> element in the PCML document.
Returns:
The integer return value for the named service program element.
Throws:
PcmlException - If an error occurs.

getIntValue

public int getIntValue(java.lang.String name)
                throws PcmlException
Returns an int value for the named element.

If the named element is String or a Number output value of a program, the value will be converted to an int.

Parameters:
name - The name of the <data> element in the PCML document.
Returns:
The integer value for the named element.
Throws:
PcmlException - If an error occurs.

getIntValue

public int getIntValue(java.lang.String name,
                       int[] indices)
                throws PcmlException
Returns an int value for the named element given indices to the data element. If the data element is an array or is an element in a structure array, an index must be specified for each dimension of the data.

If the named element is String or a Number output value of a program, the value will be converted to an int.

Parameters:
name - The name of the <data> element in the PCML document.
Returns:
The integer value for the named element.
Throws:
PcmlException - If an error occurs.

getStringValue

public java.lang.String getStringValue(java.lang.String name,
                                       int type)
                                throws PcmlException
Returns a String value for the named element.

This method is used when the string type cannot be determined until run-time. In those cases, the PCML document cannot be used to indicate the string type so this method is used to get the value using the string type that is specified.

If the named element is String or a Number output value of a program, the value will be converted to a String.

Parameters:
name - The name of the <data> element in the PCML document.
type - The bidi string type, as defined by the CDRA (Character Data Representataion Architecture).
Throws:
PcmlException - If an error occurs.
See Also:
BidiStringType

getStringValue

public java.lang.String getStringValue(java.lang.String name,
                                       int[] indices,
                                       int type)
                                throws PcmlException
Returns a String value for the named element given indices to the data element. If the data element is an array or is an element in a structure array, an index must be specified for each dimension of the data.

This method is used when the string type cannot be determined until run-time. In those cases, the PCML document cannot be used to indicate the string type so this method is used to get the value using the string type that is specified.

If the named element is String or a Number output value of a program, the value will be converted to a String.

Parameters:
name - The name of the <data> element in the PCML document.
indices - An array of indices for setting the value of an element in an array.
type - The bidi string type, as defined by the CDRA (Character Data Representataion Architecture).
Throws:
PcmlException - If an error occurs.
See Also:
BidiStringType

getMessageList

public AS400Message[] getMessageList(java.lang.String name)
                              throws PcmlException
Returns the list of AS/400 messages returned from running the program. An empty list is returned if the program has not been run yet.
Parameters:
name - The name of the <program> element in the PCML document.
Returns:
The array of messages returned by the AS/400 for the program.
Throws:
PcmlException - If an error occurs.

getOutputsize

public int getOutputsize(java.lang.String name)
                  throws PcmlException
Returns the number of bytes reserved for output for the named element.
Parameters:
name - The name of the <data> or <struct> element in the PCML document.
Returns:
The number of bytes reserved for output for the named element.
Throws:
PcmlException - If an error occurs.

getOutputsize

public int getOutputsize(java.lang.String name,
                         int[] indices)
                  throws PcmlException
Returns the number of bytes reserved for output for the named element and indices.
Parameters:
name - The name of the <data> or <struct> element in the PCML document.
indices - An array of indices for accessing the output size of an element in an array.
Returns:
The number of bytes reserved for output for the named element.
Throws:
PcmlException - If an error occurs.

getValue

public java.lang.Object getValue(java.lang.String name)
                          throws PcmlException
Returns the Java object value for the named element.

If the named element is an output value of a program, the value will be converted from AS/400 data to a Java Object.

The type of object returned depends on the description in the PCML document.
PCML DescriptionObject Returned
type=charString
type=bytebyte[]
type=int
length=2
precision=15
Short
type=int
length=2
precision=16
Integer
type=int
length=4
precision=31
Integer
type=int
length=4
precision=32
Long
type=int
length=8
precision=63
Long
type=packedBigDecimal
type=zonedBigDecimal
type=float
length=4
Float
type=float
length=8
Double

Parameters:
name - The name of the <data> element in the PCML document.
Returns:
The Java object value for the named <data> element in the PCML document.
Throws:
PcmlException - If an error occurs.

getValue

public java.lang.Object getValue(java.lang.String name,
                                 int[] indices)
                          throws PcmlException
Returns the Java object value for the named element given indices to the data element. If the data element is an array or is an element in a structure array, an index must be specified for each dimension of the data.

If the named element is an output value of a program, the value will be converted from AS/400 data to a Java Object.

The type of object returned depends on the description in the PCML document.
PCML DescriptionObject Returned
type=charString
type=bytebyte[]
type=int
length=2
precision=15
Short
type=int
length=2
precision=16
Integer
type=int
length=4
precision=31
Integer
type=int
length=4
precision=32
Long
type=int
length=8
precision=63
Long
type=packedBigDecimal
type=zonedBigDecimal
type=float
length=4
Float
type=float
length=8
Double

Parameters:
name - The name of the <data> element in the PCML document.
indices - An array of indices for accessing the value of an element in an array.
Returns:
The Java object value for the named <data> element in the PCML document.
Throws:
PcmlException - If an error occurs.

getSystem

public AS400 getSystem()
Gets the AS/400 on which programs are to be called.
Returns:
The current AS/400 for this ProgramCallDocument.
See Also:
setSystem(com.ibm.as400.access.AS400), AS400

serialize

public void serialize()
               throws PcmlException
Serializes the ProgramCallDocument. The filename of the serialized file will be of the form
docName.pcml.ser
where docName.pcml.ser is the name of the document used to construct this object.
Throws:
PcmlException - If an error occurs.

setIntValue

public void setIntValue(java.lang.String name,
                        int value)
                 throws PcmlException
Sets the Java object value for the named element using a int input.

The named element must be able to be set using a Integer object.

Parameters:
name - The name of the <data> element in the PCML document.
value - The int value for the named element.
Throws:
PcmlException - If an error occurs.

setIntValue

public void setIntValue(java.lang.String name,
                        int[] indices,
                        int value)
                 throws PcmlException
Sets the Java object value for the named element using an int input value given indices to the data element.

The named element must be able to be set using a Integer object.

Parameters:
name - The name of the <data> element in the PCML document.
indices - An array of indices for setting the value of an element in an array.
value - The int value for the named element.
Throws:
PcmlException - If an error occurs.

setStringValue

public void setStringValue(java.lang.String name,
                           java.lang.String value,
                           int type)
                    throws PcmlException
Sets the Java object value for the named element using a String input.

This method is used when the string type cannot be determined until run-time. In those cases, the PCML document cannot be used to indicate the string type so this method is used to set the value and the string type of the input value.

Parameters:
name - The name of the <data> element in the PCML document.
value - The int value for the named element.
type - The bidi string type, as defined by the CDRA (Character Data Representataion Architecture).
Throws:
PcmlException - If an error occurs.
See Also:
BidiStringType

setStringValue

public void setStringValue(java.lang.String name,
                           int[] indices,
                           java.lang.String value,
                           int type)
                    throws PcmlException
Sets the Java object value for the named element using a String input value given indices to the data element.

This method is used when the string type cannot be determined until run-time. In those cases, the PCML document cannot be used to indicate the string type so this method is used to set the value and the string type of the input value.

Parameters:
name - The name of the <data> element in the PCML document.
indices - An array of indices for setting the value of an element in an array.
value - The int value for the named element.
type - The bidi string type, as defined by the CDRA (Character Data Representataion Architecture).
Throws:
PcmlException - If an error occurs.
See Also:
BidiStringType

setDocument

public void setDocument(java.lang.String docName)
                 throws PcmlException
Sets the PCML document resource. The PCML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for a PCML source file.
Parameters:
docName - The document resource name of the PCML document for the programs to be called. The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myPcml"
Throws:
PcmlException - when the specified PCML document cannot be found

setDocument

public void setDocument(java.lang.String docName,
                        java.lang.ClassLoader loader)
                 throws PcmlException
Sets the PCML document resource. The PCML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for a PCML source file.
Parameters:
docName - The document resource name of the PCML document for the programs to be called. The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myPcml"
loader - The ClassLoader that will be used when loading the specified document resource.
Throws:
PcmlException - when the specified PCML document cannot be found

setSystem

public void setSystem(AS400 system)
Sets the AS/400 on which to call programs.
Parameters:
system - The AS/400 on which to call programs.

setValue

public void setValue(java.lang.String name,
                     java.lang.Object value)
              throws PcmlException
Sets the Java object value for the named element.

If the input value provided is not an instance of the correct Java class for the defined data type, it will be converted to the correct Java class. For example, an element defined as "type=int length=2 precision=15", will be converted to a Java Short object. In this case the value specified must be an instance of Number or String.

If the named element is an input value to a program, the value will be converted to AS/400 data when callProgram() is called.

Parameters:
name - The name of the <data> element in the PCML document.
value - The java object value for the named element. The type of Object passed must be the correct type for the element definition or a String that can be converted to the correct type.
Throws:
PcmlException - If an error occurs.

setValue

public void setValue(java.lang.String name,
                     int[] indices,
                     java.lang.Object value)
              throws PcmlException
Sets the Java object value for the named element given indices to the data element. If the data element is an array or is an element in a structure array, an index must be specified for each dimension of the data.

If the input value provided is not an instance of the correct Java class for the defined data type, it will be converted to the correct Java class. For example, an element defined as "type=int length=2 precision=15", will be converted to a Java Short object. In this case the value specified must be an instance of Number or String.

If the named element is an input value to a program, the value will be converted to AS/400 data when callProgram() is called.

Parameters:
name - The name of the <data> element in the PCML document.
indices - An array of indices for setting the value of an element in an array.
value - The java object value for the named element. The type of Object passed must be the correct type for the element definition or a String that can be converted to the correct type.
Throws:
PcmlException - If an error occurs.

setPath

public void setPath(java.lang.String program,
                    java.lang.String path)
             throws PcmlException
Allows for dynamically specifying the program path.
Parameters:
program - The name of the <program> element in the PCML document.
path - A String containing the path to the program objectto be run on the server.
Throws:
PcmlException - If an error occurs.

setThreadsafeOverride

public void setThreadsafeOverride(java.lang.String program,
                                  boolean threadsafe)
                           throws PcmlException
Allows the overriding of the threadsafe attribute of a program element.
Parameters:
program - The name of the <program> element in the PCML document.
threadsafe - A boolean indicating whether the named program element should be considered thread safe (true) or not (false).
Throws:
PcmlException - If an error occurs.

getThreadsafeOverride

public boolean getThreadsafeOverride(java.lang.String program)
                              throws PcmlException
Gets the value of the override of the threadsafe attribute of a program element.
Parameters:
program - The name of the <program> element in the PCML document.
Throws:
PcmlException - If an error occurs.