CICS® Transaction Gateway Programming Reference V3.1

com.ibm.ctg.client
Class ESIRequest

java.lang.Object
  |
  +--com.ibm.ctg.client.GatewayRequest
        |
        +--com.ibm.ctg.client.ESIRequest

public class ESIRequest
extends GatewayRequest

This class contains the details of an ESI request to the CICS Transaction Gateway. To execute the request, the ESIRequest object should be flowed to the Gateway using the JavaGateway.flow method

See Also:
GatewayRequest

Field Summary
protected  int Cics_Rc
           
protected  java.lang.String currentPassword
           
protected  int[] details
           
static int ESI_CHANGE_PASSWORD
          Call type for change password request
static int ESI_ERR_CALL_FROM_CALLBACK
          On the CICS client, the call was made from a callback routine
static int ESI_ERR_CICS_DIED
          The Specified server is no longer available
static int ESI_ERR_MAX_SESSIONS
          Not enough communication resources to satisfy request
static int ESI_ERR_MAX_SYSTEMS
          Reached limit on maxmimum number of systems
static int ESI_ERR_NO_CICS
          No CICS system Available
static int ESI_ERR_NO_SESSIONS
          No Sessions
static int ESI_ERR_NULL_NEW_PASSWORD
          The new password was set to nulls
static int ESI_ERR_NULL_OLD_PASSWORD
          The old password was set to nulls
static int ESI_ERR_NULL_PASSWORD
          The password supplied was set to nulls
static int ESI_ERR_NULL_USERID
          The userid was set to nulls
static int ESI_ERR_PASSWORD_EXPIRED
          The password has expired
static int ESI_ERR_PASSWORD_INVALID
          The password is invalid
static int ESI_ERR_PASSWORD_REJECTED
          The new password does not conform to the standards defined by the external security manager
static int ESI_ERR_PEM_NOT_ACTIVE
          The requested server does not support password expiry management
static int ESI_ERR_PEM_NOT_SUPPORTED
          Password Expiry Management is only supported over SNA and TCP62 and only on specific servers
static int ESI_ERR_RESOURCE_SHORTAGE
          Not enough resource to complete the request
static int ESI_ERR_SECURITY_ERROR
          An error was detected by the external Security Manager.
static int ESI_ERR_SYSTEM_ERROR
          An internal System Error Occurred
static int ESI_ERR_UNKNOWN_SERVER
          The requested Server could not be located
static int ESI_ERR_USERID_INVALID
          The userid is not known to the external security manager
static int ESI_NO_ERROR
          The function completed normally
static int ESI_PASSWORD_MAX
          Maximum Number of Characters for Password
static int ESI_SYSTEM_MAX
          Maximum Number of Characters for Server
static int ESI_USERID_MAX
          Maximum Number of Characters for Userid
static int ESI_VERIFY_PASSWORD
          Call type for verify password request
protected  java.lang.String newPassword
           
protected  java.lang.String server
           
protected  java.lang.String userid
           
 
Fields inherited from class com.ibm.ctg.client.GatewayRequest
ERROR_CONNECTION_FAILED, ERROR_GATEWAY_CLOSED, ERROR_REPLY_MISMATCH, ERROR_UNKNOWN_REQUEST_TYPE, ERROR_WORK_WAS_REFUSED
 
Constructor Summary
ESIRequest()
          Default constructor, this leaves all the values set to their defaults.
 
Method Summary
(package private) static void ()
          The purpose of this static initializer is to get the appropriate ResourceBundle class.
 void changePassword()
          Sets the ESI request object to be a change Password Request
static ESIRequest changePassword(java.lang.String strUserid, java.lang.String strCurrentPassword, java.lang.String strNewPassword, java.lang.String strServer)
          This method returns a new ESI Request object which can be used to invoke a changePassword request.
 int getCallType()
          This method returns the Call_Type field of this ESIRequest object.
 java.lang.String getCallTypeString()
          This method returns a String describing the Call_Type field of this ESIRequest object.
 int getCicsRc()
          Gets the CICS return code set in this object.
 java.lang.String getCicsRcString()
          Gets the CICS return code set in this object and returns it as a String.
 java.lang.String getCurrentPassword()
          This method returns a String of the Current Password defined
 java.util.Calendar getExpiry()
          This method returns a java.util.Calendar object containing the Date/Time of when the userid/password will expire on the server.
 int getInvalidCount()
          This method returns a int containing the number of invalid password attempts for that userid on the specified server.
 java.util.Calendar getLastAccess()
          This method returns a java.util.Calendar object containing the Date/Time of when the userid/password was last accessed on the server.
 java.util.Calendar getLastVerified()
          This method returns a java.util.Calendar object containing the Date/Time of when the userid/password was last verified on the server.
 java.lang.String getNewPassword()
          This method returns a String of the New Password defined This will only be set if you are using the changePassword call
 int getRc()
          Gets the return code set in this object.
 java.lang.String getServer()
          This method returns a String of the Server defined
 java.lang.String getUserid()
          This method returns a String of the current Userid defined
 void setCurrentPassword(java.lang.String strPassword)
          Set the current password for this object.
 void setNewPassword(java.lang.String strPassword)
          Set the new password for this object.
 void setServer(java.lang.String strServer)
          Sets the Server to be used for this object.
 void setUserid(java.lang.String strUserid)
          Set the userid for this object.
 void verifyPassword()
          Sets the ESI request object to be a verify Password Request
static ESIRequest verifyPassword(java.lang.String strUserid, java.lang.String strCurrentPassword, java.lang.String strServer)
          This method returns a new ESI Request object which can be used to invoke a verifyPassword request.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ESI_USERID_MAX

public static final int ESI_USERID_MAX
Maximum Number of Characters for Userid

ESI_PASSWORD_MAX

public static final int ESI_PASSWORD_MAX
Maximum Number of Characters for Password

ESI_SYSTEM_MAX

public static final int ESI_SYSTEM_MAX
Maximum Number of Characters for Server

ESI_NO_ERROR

public static final int ESI_NO_ERROR
The function completed normally

ESI_ERR_NO_CICS

public static final int ESI_ERR_NO_CICS
No CICS system Available

ESI_ERR_CICS_DIED

public static final int ESI_ERR_CICS_DIED
The Specified server is no longer available

ESI_ERR_SYSTEM_ERROR

public static final int ESI_ERR_SYSTEM_ERROR
An internal System Error Occurred

ESI_ERR_RESOURCE_SHORTAGE

public static final int ESI_ERR_RESOURCE_SHORTAGE
Not enough resource to complete the request

ESI_ERR_NO_SESSIONS

public static final int ESI_ERR_NO_SESSIONS
No Sessions

ESI_ERR_UNKNOWN_SERVER

public static final int ESI_ERR_UNKNOWN_SERVER
The requested Server could not be located

ESI_ERR_CALL_FROM_CALLBACK

public static final int ESI_ERR_CALL_FROM_CALLBACK
On the CICS client, the call was made from a callback routine

ESI_ERR_SECURITY_ERROR

public static final int ESI_ERR_SECURITY_ERROR
An error was detected by the external Security Manager. The most likely explaination is that the userid has been revoked.

ESI_ERR_MAX_SYSTEMS

public static final int ESI_ERR_MAX_SYSTEMS
Reached limit on maxmimum number of systems

ESI_ERR_MAX_SESSIONS

public static final int ESI_ERR_MAX_SESSIONS
Not enough communication resources to satisfy request

ESI_ERR_NULL_USERID

public static final int ESI_ERR_NULL_USERID
The userid was set to nulls

ESI_ERR_NULL_OLD_PASSWORD

public static final int ESI_ERR_NULL_OLD_PASSWORD
The old password was set to nulls

ESI_ERR_NULL_NEW_PASSWORD

public static final int ESI_ERR_NULL_NEW_PASSWORD
The new password was set to nulls

ESI_ERR_PEM_NOT_SUPPORTED

public static final int ESI_ERR_PEM_NOT_SUPPORTED
Password Expiry Management is only supported over SNA and TCP62 and only on specific servers

ESI_ERR_PEM_NOT_ACTIVE

public static final int ESI_ERR_PEM_NOT_ACTIVE
The requested server does not support password expiry management

ESI_ERR_PASSWORD_EXPIRED

public static final int ESI_ERR_PASSWORD_EXPIRED
The password has expired

ESI_ERR_PASSWORD_INVALID

public static final int ESI_ERR_PASSWORD_INVALID
The password is invalid

ESI_ERR_PASSWORD_REJECTED

public static final int ESI_ERR_PASSWORD_REJECTED
The new password does not conform to the standards defined by the external security manager

ESI_ERR_USERID_INVALID

public static final int ESI_ERR_USERID_INVALID
The userid is not known to the external security manager

ESI_ERR_NULL_PASSWORD

public static final int ESI_ERR_NULL_PASSWORD
The password supplied was set to nulls

ESI_VERIFY_PASSWORD

public static final int ESI_VERIFY_PASSWORD
Call type for verify password request

ESI_CHANGE_PASSWORD

public static final int ESI_CHANGE_PASSWORD
Call type for change password request

userid

protected java.lang.String userid

currentPassword

protected java.lang.String currentPassword

newPassword

protected java.lang.String newPassword

server

protected java.lang.String server

Cics_Rc

protected int Cics_Rc

details

protected int[] details
Constructor Detail

ESIRequest

public ESIRequest()
Default constructor, this leaves all the values set to their defaults.

You will need to use the various setter methods to define the required parameters for the type of call you require

Method Detail

static void ()
The purpose of this static initializer is to get the appropriate ResourceBundle class. Client-side resource bundles (for CICS requests) have the naming format: CicsResourceBundle.java This class is the highest level resource bundle and the messages are in US English. If the language associated with the default locale is not US English then the specific resource bundle (if it exists) will have the format: CicsResourceBundle_fr.java (or CicsResourceBundle_fr_FR.java). The 'getBundle()' method of the ResourceBundle class looks for the most specific (appropriate) resource bundle first and if it does not find this works its way up to the least specific resource bundle i.e. CicsResourceBundle.java. So, messages will appear in US English if there are no appropriate resource bundles.

getUserid

public java.lang.String getUserid()
This method returns a String of the current Userid defined

Returns:
String The Current userid

getCurrentPassword

public java.lang.String getCurrentPassword()
This method returns a String of the Current Password defined

Returns:
String The Current password

getNewPassword

public java.lang.String getNewPassword()
This method returns a String of the New Password defined This will only be set if you are using the changePassword call

Returns:
String The New password

getServer

public java.lang.String getServer()
This method returns a String of the Server defined

Returns:
String The Server defined

getLastVerified

public java.util.Calendar getLastVerified()
This method returns a java.util.Calendar object containing the Date/Time of when the userid/password was last verified on the server. This call will only return information if a successful verifyPassword or changePassword has been flowed, otherwise null is returned.

Returns:
java.util.Calendar Last Verified Information (null if no info)

getExpiry

public java.util.Calendar getExpiry()
This method returns a java.util.Calendar object containing the Date/Time of when the userid/password will expire on the server. This call will only return information if a successful verifyPassword or changePassword has been flowed, otherwise null is returned.

Returns:
java.util.Calendar Last Verified Information (null if no info)

getLastAccess

public java.util.Calendar getLastAccess()
This method returns a java.util.Calendar object containing the Date/Time of when the userid/password was last accessed on the server. This call will only return information if a successful verifyPassword or changePassword has been flowed, otherwise null is returned.

Returns:
java.util.Calendar Last Verified Information (null if no info)

getInvalidCount

public int getInvalidCount()
This method returns a int containing the number of invalid password attempts for that userid on the specified server. This call will only return information if a successful verifyPassword or changePassword has been flowed, otherwise -1 is returned.

Returns:
int Invalid attempts (-1 if no info)

getRc

public int getRc()
Gets the return code set in this object. If a Gateway error code is set this is returned. However if there is no Gateway error code, then any CICS return code is returned. If this method returns zero, it can be assumed that no errors have occured.
Returns:
int The return code

getCicsRc

public int getCicsRc()
Gets the CICS return code set in this object.
Returns:
int The return code

getCicsRcString

public java.lang.String getCicsRcString()
Gets the CICS return code set in this object and returns it as a String.

The String returned is the name of the appropriate Java constant e.g. if the Cics_Rc is ESI_NO_ERROR, then the String returned will be "ESI_NO_ERROR". If the Cics_Rc is unknown then the String returned will be "ESI_UNKNOWN_CICS_RC".

NOTE: for CICS return codes that may have more than one meaning the String returned is a concatenation of the return codes. The two concatenated Strings are: ESI_ERR_NULL_OLD_PASSWORD_OR_ESI_ERR_NULL_PASSWORD

Returns:
String The return code

getCallType

public int getCallType()
This method returns the Call_Type field of this ESIRequest object. This will either be the enumerated types ESI_VERIFY_PASSWORD or ESI_CHANGE_PASSWORD
Returns:
int The Call_Type

getCallTypeString

public java.lang.String getCallTypeString()
This method returns a String describing the Call_Type field of this ESIRequest object.

The String returned is the name of the appropriate Java constant either ESI_VERIFY_PASSWORD or ESI_CHANGE_PASSWORD

Returns:
String The Call_Type as a String

setUserid

public void setUserid(java.lang.String strUserid)
               throws java.lang.IllegalArgumentException
Set the userid for this object. If the userid is greater than 10 characters then and IllegalArgumentException is thrown

Parameters:
strUserid - String The userid
Throws:
java.lang.IllegalArgumentException - if the parameter value is greater than 10 characters

setCurrentPassword

public void setCurrentPassword(java.lang.String strPassword)
                        throws java.lang.IllegalArgumentException
Set the current password for this object. If the password is greater than 10 characters then and IllegalArgumentException is thrown

Parameters:
strPassword - String The Current Password
Throws:
java.lang.IllegalArgumentException - if the parameter value is greater than 10 characters

setNewPassword

public void setNewPassword(java.lang.String strPassword)
                    throws java.lang.IllegalArgumentException
Set the new password for this object. If the new password is greater than 10 characters then an IllegalArgumentException is thrown

Parameters:
strPassword - String The New Password
Throws:
java.lang.IllegalArgumentException - if the parameter value is greater than 10 characters

setServer

public void setServer(java.lang.String strServer)
               throws java.lang.IllegalArgumentException
Sets the Server to be used for this object. If the server given is greater than 8 characters then an IllegalArgumentException is thrown

Parameters:
strServer - String The Server
Throws:
java.lang.IllegalArgumentException - if the parameter value is greater than 10 characters

verifyPassword

public void verifyPassword()
Sets the ESI request object to be a verify Password Request

changePassword

public void changePassword()
Sets the ESI request object to be a change Password Request

verifyPassword

public static ESIRequest verifyPassword(java.lang.String strUserid,
                                        java.lang.String strCurrentPassword,
                                        java.lang.String strServer)
This method returns a new ESI Request object which can be used to invoke a verifyPassword request. An IllegalArgument exception will be thrown if the userid or password are greater than 10 characters or the Server is greater than 8 characters.

Parameters:
strUserid - String The userid
strCurrentPassword - String The current Password
strServer - String The Server
Throws:
java.lang.IllegalArgumentException - if the parameters are too long

changePassword

public static ESIRequest changePassword(java.lang.String strUserid,
                                        java.lang.String strCurrentPassword,
                                        java.lang.String strNewPassword,
                                        java.lang.String strServer)
                                 throws java.lang.IllegalArgumentException
This method returns a new ESI Request object which can be used to invoke a changePassword request. An IllegalArgument exception will be thrown if the userid or passwords are greater than 10 characters or the Server is greater than 8 characters.

Parameters:
strUserid - String The userid
strCurrentPassword - String The current Password
strNewPassword - String The New Password
strServer - String The Server
Throws:
java.lang.IllegalArgumentException - if the parameters are too long

© Copyright IBM Corp. 1994, 1999