Connecting to an IMS database by using the IMS Universal DL/I driver

Before you can execute DL/I calls from your IMS Universal DL/I driver application, you must connect to an IMS database.

1. Create an IMSConnectionSpec instance by calling the createIMSConnectionSpec method in the IMSConnectionSpecFactory class.
2. Set the following connection properties for the IMSConnectionSpec instance.

   DatastoreName

   The name of the IMS data store to access.

   • When using type-4 connectivity, the DatastoreName property must match either the name of the data store defined to ODBM or be blank. The data store name is defined in the ODBM CSLDCxxx PROCLIB member using either the DATASTORE(NAME=name) or DATASTORE(NAME=name, ALIAS(NAME=aliasname)) parameter. If an alias is specified, you must specify the aliasname as the value of the datastoreName property. If the DatastoreName value is left blank (or not supplied), IMS Connect connects to any available instance of ODBM as it is assumed that data sharing is enabled between all datastores defined to ODBM.
   • When using type-2 connectivity, set the DatastoreName property to the IMS subsystem alias. This is not required to be set for the Java™ Dependent Region run time.

   DatabaseName

   The location of the database metadata representing the target IMS database.

   The DatabaseName property can be specified in one of two ways, depending on whether the metadata is stored in the IMS catalog or as a static metadata class generated by the IMS Enterprise Suite Explorer for Development:

   • If your IMS system uses the IMS catalog, the DatabaseName property is the name of the PSB that your application uses to access the target IMS database.
   • If you are using the IMS Explorer for Development, the databaseName property is the fully qualified name of the Java metadata class generated by the IMS Explorer for Development. The URL must be prefixed with class:// (for example, class://com.foo.BMP255DatabaseView).

   In a J2C Connection Factory environment, the DatabaseName property can be overridden for an individual connection without affecting the default value specified for the resource adapter.

   MetadataURL

   The location of the database metadata representing the target IMS database.

   This property is deprecated. Use DatabaseName instead.

   The MetadataURL property is the fully qualified name of the Java metadata class generated by the IMS Enterprise Suite Explorer for Development. The URL must be prefixed with class:// (for example, class://com.foo.BMP255DatabaseView).

   In a J2C Connection Factory environment, the MetadataURL property can be overridden for an individual connection without affecting the default value specified for the resource adapter.

   PortNumber

   The TCP/IP server port number to be used to communicate with IMS Connect. The port number is defined using the DRDAPORT parameter on the ODACCESS statement in the IMS Connect configuration PROCLIB member. The default port number is 8888. Do not set this property when using type-2 connectivity.

   DatastoreServer

   The name or IP address of the data store server (IMS Connect). You can provide either the host name (for example, dev123.svl.ibm.com) or the IP address (for example, 192.166.0.2). Do not set this property when using type-2 connectivity.

   DriverType

   The type of driver connectivity to use (value must be IMSConnectionSpec.DRIVER_TYPE_4 for type-4 connectivity or IMSConnectionSpec.DRIVER_TYPE_2 for type-2 connectivity).

   allMetadata

   Optional. When this property is set to true, the DatabaseMetadata interface returns information for all resources in the IMS catalog. When the property is set to false, the DatabaseMetadata interface returns information for the allocated PSB. The default value for this property is false.

   IMS 14 APAR PI62871 (PTF UI40491) is required for this property.

   initStatusGroup

   Optional. When a connection is made and the PSB is allocated, this property will indicate that the driver should automatically issue an INIT STATUS GROUPA or INIT STATUS GROUPB if a value of 'A' or 'B' is provided. The default will not issue an INIT STATUS GROUP call.

   sslConnection

   Optional. Indicates if this connection uses Secure Sockets Layer (SSL) for data encryption. Set this property to true to enable SSL, or to false otherwise. Do not set this property when using type-2 connectivity.

   sslKeyStoreType

   Optional. Specifies the format of the file that contains cryptographic objects needed to establish a secure socket connection. The valid values are JKS and PKCS12. This value is only used when sslConnection is set to true and sslKeyStoreType is not specified. The sslKeyStoreType parameter defaults to JKS.

   sslSecureSocketProtocol

   Optional. Specifies the cryptographic communication protocol for the new connection. Specify a protocol that is supported by the server and provides the highest level of security. The valid values are SSL, SSLv3, TLSv1.1, and TLSv1.2. This value is only used when sslConnection is set to true. If sslConnection is set to true and sslSecureSocketProtocol is not specified, a default protocol will be determined at runtime by the JRE and the server.

   sslTrustStoreLocation

   Optional. Specifies the location of the cryptographic trust store file for the new connection. This value is only used when sslConnection is set to true.

   sslTrustStorePassword

   Optional. Specifies the password to access the cryptographic trust store file. This value is only used when sslConnection is set to true.

   sslKeyStoreLocation

   Optional. Specifies the location of the cryptographic key store file for the new connection. This value is only used when sslConnection is set to true.

   sslKeyStorePassword

   Optional. Specifies the password to access the cryptographic key store file. This value is only used when sslConnection is set to true.

   loginTimeout

   Optional. Specifies the number of seconds that the driver waits for a response from the server before timing out a connection initialization or server request. Set this property to a non-negative integer for the number of seconds. Set this property to 0 for an infinite timeout length. Do not set this property when using type-2 connectivity.

   user

   The user name for the connection to IMS Connect provided by your RACF® administrator. Do not set this property when using type-2 connectivity.

   password

   The password for the connection to IMS Connect provided by your RACF administrator. Do not set this property when using type-2 connectivity.

   dbViewLocation

   Optional. Specifies the fully qualified path to a databaseView metadata class. You can use this property to include a metadata class that is not located in your project path.

   treatInvalidDecimalAsNull

   Optional. Indicates whether to interpret certain Decimal values that appear invalid in Java applications (such as PACKEDDECIMAL and ZONEDDECIMAL with invalid sign bits) as null. By default, this property is false, and a conversion exception is thrown when the Java applications are processing invalid values.

3. Pass the connection request properties to the PSBFactory class to create the PSB instance.
   When the PSB instance is created successfully, a connection is established to the database.
4. When you are finished with a connection to the IMS database from a IMS Universal DL/I driver application, you must close the connection to the database by calling the close method on the PSB instance.

IMSConnectionSpec connSpec = IMSConnectionSpecFactory.createIMSConnectionSpec();
connSpec.setDatastoreName("SYS1");
connSpec.setDatastoreServer("9.876.543.21");
connSpec.setPortNumber(8888);
connSpec.setDatabaseName("class://testdb.jdbo.HospitalDatabaseView");
connSpec.setSSLConnection(true);
connSpec.setLoginTimeout(10);
connSpec.setUser("usr");
connSpec.setPassword("usrpwd");
connSpec.setDriverType(IMSConnectionSpec.DRIVER_TYPE_4);
PSB psb = PSBFactory.createPSB(connSpec);