com.ibm.as400.access

Class ServiceProgramCall

  • All Implemented Interfaces:
    java.io.Serializable

    public class ServiceProgramCall
extends ProgramCall
    Allows a user to call an IBM i service program. Input data is passed via input parameters, and output data is accessed via output parameters. ProgramParameter objects are used to pass data between the Java program and the service program.

    Limitations of this class:

    • The service program must be on an IBM i system running V4R4 or later.
    • Up to seven parameters can be passed to the service program.
    • The return value must be void or numeric. This class does not support calling service programs that return a pointer.
    • Parameters can be "pass by reference" or "pass by value".
      • When pass by reference, the data is copied from Java storage to system storage, then a pointer to the system storage is passed to the service program.
      • Up to four bytes can be passed by value. Parameters longer than four bytes must be passed by reference which may require a change to the service program.
      • Procedures defined using "#pragma argopt" are not supported.

    The name of the service program to call is the fully qualified name in the integrated file system. The extension is ".SRVPGM". For example, to call MySrvPgm in MyLib, the program name is /QSYS.LIB/MYLIB.LIB/MYSRVPGM.SRVPGM.

    Service program entry point notes:

    • The service program entry point to call is supplied by the Java program. The entry point name is case sensitive. If the run() method fails with the message "CPF226E - Value for a parameter was not valid.", there is a good chance the entry point name is incorrect.
    • The service program entry point name is converted from a Java String to an array of EBCDIC bytes before being sent to the system. By default this conversion is performed using CCSID 37, not the job CCSID which Toolbox classes usually use for conversion. This is because the entry point name is set when the service program is built. CCSID 37 is the default because most IBM supplied service programs set the entry point name based on CCSID 37. A setProcedureName() method exists which lets you override the default.

    The following example calls procedure int_int in service program ENTRYPTS in library MYPGM. The procedure takes one input parameter, an integer, and returns an integer. 

        // Create a single parameter parameter list.
    ProgramParameter[] parameterList = new ProgramParameter[1];

    // Create the input parameter.  We are sending the number 9 to the service program.
    AS400Bin4 bin4 = new AS400Bin4();
    byte[] parameter = bin4.toBytes(9);
    parameterList[0] = new ProgramParameter(parameter);

    // Construct the system object.  The service program is on this system.
    AS400 system = new AS400("mySystem");

    // Construct the ServiceProgramCall object.
    ServiceProgramCall sPGMCall = new ServiceProgramCall(system);

    // Set the fully qualified service program and the parameter list.
    sPGMCall.setProgram("/QSYS.LIB/MYPGM.LIB/ENTRYPTS.SRVPGM", parameterList);

    // Set the procedure to call in the service program.
    sPGMCall.setProcedureName("int_int");

    // Set the format of returned value.  The program we call returns an integer.
    sPGMCall.setReturnValueFormat(ServiceProgramCall.RETURN_INTEGER);

    // Call the service program.
    if (sPGMCall.run() != true)
    {
        // Get the error messages when the call fails.
        AS400Message[] messageList = sPGMCall.getMessageList();
        for (int i = 0; i < messageList.length; ++i)
        {
            System.out.println(messageList[i].getText());
        }
    }
    else
    {
        // Get the returned value when the call is successful.
        int i = bin4.toInt(sPGMCall.getReturnValue());
        System.out.println("Result is: " + i);
    }

    NOTE: There are two ways to run a service program in an iasp. Users can call a service program directly with path prefixed with the iasp information like "/IASP1/QSYS.LIB/MYPGM.LIB/ENTRYPTS.SRVPGM". Users can also call AS400.setIASPGroup to set the asp group information firstly, then call the service program in regular library-qualified object name syntax. The second way is recommended. For example: 

        // Call a service program on system named "Hal" on asp "iasp1"
    AS400 system = new AS400("Hal");
    system.setIASPGroup("iasp1"); //If do not use *CURUSR for current library and library list, call other setIASPGroup interfaces.
    ServiceProgramCall sPGMCall = new ServiceProgramCall(system);
    sPGMCall.setProgram("/QSYS.LIB/MYPGM.LIB/ENTRYPTS.SRVPGM");
    See Also:
    Serialized Form

    • Field Detail

      • NO_RETURN_VALUE

        public static final int NO_RETURN_VALUE
        Constant indicating the service program returns void.
        See Also:
        Constant Field Values

      • RETURN_INTEGER

        public static final int RETURN_INTEGER
        Constant indicating the service program returns an integer.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ServiceProgramCall

        public ServiceProgramCall()
        Constructs a ServiceProgramCall object. A default ServiceProgramCall object is created. The system, program name, procedure name and parameters, must be set before calling the program.

      • ServiceProgramCall

        public ServiceProgramCall(AS400 system)
        Constructs a ServiceProgramCall object. A ServiceProgramCall object representing the program on system is created. The program name, procedure name and parameters, must be set before calling the program.
        Parameters:
        system - The system that contains the program.

      • ServiceProgramCall

        public ServiceProgramCall(AS400 system,
                  java.lang.String serviceProgram,
                  ProgramParameter[] parameterList)
        Constructs a ServiceProgramCall object. A ServiceProgramCall object representing the program on system with name serviceProgram and parameters parameterList created. The service program's procedure name must be set before calling the program.
        Parameters:
        system - The system which contains the program.
        serviceProgram - The service program name as a fully qualified name in the integrated file system.
        parameterList - A list of up to 7 parameters with which to call the program.

      • ServiceProgramCall

        public ServiceProgramCall(AS400 system,
                  java.lang.String serviceProgram,
                  java.lang.String procedureName,
                  ProgramParameter[] parameterList)
        Constructs a ServiceProgramCall object. A ServiceProgramCall object representing the program on system with name serviceProgram, procedure name procedureName, and parameters parameterList, is created.
        Parameters:
        system - The system which contains the program.
        serviceProgram - The program name as a fully qualified name in the integrated file system.
        procedureName - The procedure in the service program to call.
        parameterList - A list of up to 7 parameters with which to call the program.

      • ServiceProgramCall

        public ServiceProgramCall(AS400 system,
                  java.lang.String serviceProgram,
                  java.lang.String procedureName,
                  int returnValueFormat,
                  ProgramParameter[] parameterList)
        Constructs a ServiceProgramCall object. A ServiceProgramCall object representing the program on system with name serviceProgram, procedure name procedureName, parameters parameterList, and returning a value as specified in returnValueFormat, is created.
        Parameters:
        system - The system which contains the program.
        serviceProgram - The program name as a fully qualified name in the integrated file system.
        procedureName - The procedure in the service program to call.
        returnValueFormat - The format of the returned data. The value must be one of the following:
        parameterList - A list of up to 7 parameters with which to call the program.

    • Method Detail

      • getErrno

        public int getErrno()
        Returns the error number (errno). If the service program returns an integer and an errno, use this method to retrieve the errno. Zero is returned if the service program returns an integer but no errno.

        The errno is valid only when the return code is non-zero. Service programs are not required to reset the errno each time the API is called, so the errno may not be reset from a previous call. Suppose, for example, calling an entry point the first time fails so the return code and errno are both non-zero. If the next call works, the return code will be zero but the errno may have the non-zero value from the previous call of the entry point. Checking only the errno would indicate the second call failed when it actually worked. Call this method only when a call to getIntegerReturnValue returns a non-zero value.

        Returns:
        The return data.

      • getIntegerReturnValue

        public int getIntegerReturnValue()
        Returns the return data when the service program returns an integer.
        Returns:
        The return data.

      • getProcedureName

        public java.lang.String getProcedureName()
        Returns the service program procedure to be called. If the name has not been set, an empty string ("") is returned.
        Returns:
        The service program procedure to be called.

      • getReturnValue

        public byte[] getReturnValue()
        Returns the data returned from the service program. The data is returned as a byte array. If no data is returned or if the service program has not yet been called, null is returned.
        Returns:
        The data as a byte array.

      • getReturnValueFormat

        public int getReturnValueFormat()
        Returns the format of the returned data.
        Returns:
        The format of the returned data. Possible values are:

      • run

        public boolean run(java.lang.String serviceProgram,
          ProgramParameter[] parameterList)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException,
                   ObjectDoesNotExistException,
                   java.beans.PropertyVetoException
        Calls the service program. Calls the specified service program with the specified parameters. The system and service program procedure name must be set before calling this method.
        Overrides:
        run in class ProgramCall
        Parameters:
        serviceProgram - The program name as a fully qualified name in the integrated file system.
        parameterList - A list of up to 7 parameters with which to call the program.
        Returns:
        true if the call is successful, false otherwise.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
        ObjectDoesNotExistException - If the system object does not exist.
        java.beans.PropertyVetoException - If a change for a property is vetoed.

      • run

        public boolean run(AS400 system,
          java.lang.String serviceProgram,
          java.lang.String procedureName,
          int returnValueFormat,
          ProgramParameter[] parameterList)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException,
                   ObjectDoesNotExistException,
                   java.beans.PropertyVetoException
        Calls the service program.
        Parameters:
        system - The system which contains the program.
        serviceProgram - The program name as a fully qualified name in the integrated file system.
        procedureName - The procedure in the service program to call.
        returnValueFormat - The format of the returned data. The value must be one of the following:
        parameterList - A list of up to 7 parameters with which to call the program.
        Returns:
        true if program calls is successful
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
        ObjectDoesNotExistException - If the system object does not exist.
        java.beans.PropertyVetoException - If a change for a property is vetoed.

      • setAlignOn16Bytes

        public void setAlignOn16Bytes(boolean align)
        Sets whether to align the first parameter on a 16-byte boundary. Some service programs require that the "receiver variable" (typically the first parameter) be aligned on a 16-byte boundary. By default, no alignment is done.
        Parameters:
        align - Whether to align the first parameter on a 16-byte boundary.

      • setProcedureName

        public void setProcedureName(java.lang.String procedureName)
                      throws java.beans.PropertyVetoException
        Sets the service program procedure to call.
        Parameters:
        procedureName - The procedure in the service program to call.
        Throws:
        java.beans.PropertyVetoException - If a change for the value of procedureName is vetoed.

      • setProcedureName

        public void setProcedureName(java.lang.String procedureName,
                    int procedureNameCCSID)
                      throws java.beans.PropertyVetoException
        Sets the service program procedure to call.
        Parameters:
        procedureName - The procedure in the service program to call.
        procedureNameCCSID - The CCSID to use when converting the procedure name from a Java String to EBCDIC.
        Throws:
        java.beans.PropertyVetoException - If a change for the value of procedureName is vetoed.

      • setProgram

        public void setProgram(java.lang.String serviceProgram)
                throws java.beans.PropertyVetoException
        Sets the path name of the service program.
        Overrides:
        setProgram in class ProgramCall
        Parameters:
        serviceProgram - The fully qualified integrated file system path name to the service program. The library and service program name must each be 10 characters or less.
        Throws:
        java.beans.PropertyVetoException - If the change is vetoed.

      • setReturnValueFormat

        public void setReturnValueFormat(int returnValueFormat)
                          throws java.beans.PropertyVetoException
        Sets the format of the returned data.
        Parameters:
        returnValueFormat - The format of the returned data. The value must be one of the following:
        Throws:
        java.beans.PropertyVetoException - If a change for the value of returnValueFormat is vetoed.
JTOpen 11.2