CORBASERVER definition attributes

Read syntax diagramSkip visual syntax diagram
>>-CORBASERVER(name)--GROUP(groupname)--+-------------------+--->
                                        '-DESCRIPTION(text)-'   

   .-AUTOPUBLISH(NO)--.                           
>--+------------------+--+--------------------+----------------->
   '-AUTOPUBLISH(YES)-'  '-CERTIFICATE(label)-'   

>--+---------------------+--+--------------------+-------------->
   '-CIPHERS(cipherlist)-'  '-DJARDIR(directory)-'   

>--HOST(hostname)--+--------------------+----------------------->
                   '-JNDIPREFIX(prefix)-'   

   .-SESSBEANTIME(00,00,10)-.  .-SHELF(/var/cicsts)-.   
>--+------------------------+--+--------------------+----------->
   +-SESSBEANTIME(00,00,00)-+  '-SHELF(directory)---'   
   '-SESSBEANTIME(dd,hh,mm)-'                           

   .-STATUS(ENABLED)--.   
>--+------------------+----------------------------------------->
   '-STATUS(DISABLED)-'   

>--UNAUTH(tcpipservice)--+-----------------+--+--------------------------+-><
                         '-ASSERTED(char8)-'  +-CLIENTCERT(tcpipservice)-+   
                                              '-SSLUNAUTH(tcpipservice)--'   

ASSERTED(tcpipservice)
specifies the 8–character name of a TCPIPSERVICE that defines the characteristics of the port which is used for inbound IIOP with asserted identity authentication.
AUTOPUBLISH({NO|YES})
specifies whether the contents of a deployed JAR file should be automatically published to the namespace when the DJAR definition is successfully installed into this CorbaServer. “Successfully installed” means that the DJAR is INSERVICE. The default is NO.

Specifying YES causes beans to be automatically published to the namespace when a DJAR is successfully installed. It does not cause beans to be automatically retracted when a DJAR is discarded.

CERTIFICATE(label)
specifies the label of an X.509 certificate that is used as a client certificate during the SSL handshake for outbound IIOP connections. If this attribute is omitted, the default certificate defined in the key ring for the CICS region user ID is used.

Certificate labels can be up to 32 bytes long.

The distinguished name within the specified certificate provides inputs to the distinguished name user-replaceable program, DFHEJDNX.

Start of changeCIPHERS(cipherlist)End of change
Start of changeEnd of change
Start of changeSpecifies a string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes. When you use the CEDA transaction to define the resource, CICS automatically initializes the attribute with a default list of acceptable codes. Start of changeFor CICS to initialize the attribute, the KEYRING system initialization parameter must be specified in the CICS region where you are running CEDA. If KEYRING is not set, CICS does not initialize the attribute.End of change The default list of codes depends on the level of encryption that is specified by the ENCRYPTION system initialization parameter.
  • For ENCRYPTION=WEAK, the default value is 03060102
  • For ENCRYPTION=MEDIUM, the initial value is 0903060102
  • For ENCRYPTION=STRONG, the initial value is 0504352F0A0903060102

You can reorder the cipher codes or remove them from the initial list. However, you cannot add cipher codes that are not in the default list for the specified encryption level. To reset the value to the default list of codes, delete all of the cipher suite codes and the field will automatically repopulate with the default list.

See Cipher suites for more information.

End of change
CLIENTCERT(tcpipservice)
specifies the 8–character name of a TCPIPSERVICE that defines the characteristics of the port which is used for inbound IIOP with SSL client certificate authentication. This attribute is optional. You cannot specify both the CLIENTCERT and SSLUNAUTH attributes.
Acceptable characters:
A-Z 0-9 $ @ #
Unless you are using the CREATE command, any lowercase characters you enter are converted to uppercase.
CORBASERVER(name)
specifies the 1-4 character name of the CorbaServer.
Acceptable characters:
A-Z a-z 0-9
For information about entering mixed case information, see Entering mixed case attributes.
Do not use names beginning with DFH, because these characters are reserved for use by CICS.
DESCRIPTION(text)
You can provide a description of the resource you are defining in this field. The description text can be up to 58 characters in length. There are no restrictions on the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right one. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.
DJARDIR(directory)
specifies the 1–255 character fully-qualified name of the deployed JAR file directory (also known as the pickup directory) on HFS. Start of change
Acceptable characters:
A-Z a-z 0-9 . / _ # @
For information about entering mixed case information, see Entering mixed case attributes.
End of change

If specified, DJARDIR must refer to a valid HFS directory to which the CICS region has at least read access.

The pickup directory is where you place deployed JAR files that you want to be installed into the CorbaServer by the CICS scanning mechanism. When the CORBASERVER definition is installed, CICS scans the pickup directory and automatically installs any deployed JAR files it finds there. (This automatic scan occurs regardless of whether the CorbaServer is installed in enabled or disabled state.)

CICS assumes that any files in the pickup directory that end in .jar and have a base filename of 1–32 characters are EJB deployed JAR files. It copies them to its shelf directory and dynamically creates and installs DJAR definitions for them. The name of the DJAR definition is the name of the deployed JAR file on HFS. For example, a deployed JAR file named /var/cicsts/pickup/TheThreeBears.jar results in a DJAR definition named TheThreeBears.

After the CorbaServer has been installed, you can add more deployed JAR files to the pickup directory. CICS installs them in either of the folowing situations:
  • When instructed to by means of an explicit EXEC CICS or CEMT PERFORM CORBASERVER SCAN command. (This command works only when the CorbaServer is in a steady state—that is, when it is in ENABLED or DISABLED state, but not when it is in ENABLING, DISABLING, or DISCARDING state.)
  • When instructed to by the resource manager for enterprise beans (otherwise known as the RM for enterprise beans), which issues a PERFORM CORBASERVER SCAN command on your behalf. (The resource manager for enterprise beans is described in the CICS Operations and Utilities Guide).

After the CorbaServer has been installed, you can also put updated versions of deployed JAR files into the pickup directory. When you issue a PERFORM CORBASERVER SCAN command (either explicitly or by means of the RM for enterprise beans), CICS detects that an update has occurred and updates both the LASTMODTIME, DATESTAMP, and TIMESTAMP attributes of the installed DJAR definition and the shelf copy of the deployed JAR file, to reflect the pickup directory change.

Note:
  1. If you use the scanning mechanism in a production region, be aware of the security implications: specifically, the possibility of CICS command security on DJAR definitions being circumvented. To guard against this, we recommend that user IDs given write access to the HFS deployed JAR file directory should be restricted to those given RACF® authority to create and update DJAR and CORBASERVER definitions.
  2. If you do not specify a value for DJARDIR, no automatic scan takes place on installation of the CorbaServer. PERFORM CORBASERVER SCAN commands (whether explicit or issued by the RM for enterprise beans) will fail.
  3. The installation of the CorbaServer fails if the value of DJARDIR is not blank but does not refer to a valid HFS directory to which the CICS region has read access.
  4. The fact that resource names must be unique in the CSD has several implications for the scanning mechanism:
    1. Different CorbaServers in the same CICS region must use different DJARDIR directories. (Otherwise, performing a scan against different CorbaServers would result in multiple sets of identically-named DJAR definitions, each set pointing at a different CorbaServer. CICS rejects all such sets of definitions except the first.)
    2. For the same reason, you must not place an identically-named deployed JAR file into multiple DJARDIR directories in the same CICS region.
      If you want to install the same set of beans into more than one CorbaServer in the same CICS region, you should do either of the following:
      1. Name the deployed JAR file differently in each DJARDIR directory.
      2. Use static definitions. That is, create multiple (differently-named) static DJAR definitions, pointing at the same deployed JAR file on HFS but at different CorbaServers.
  5. Different CICS regions may share the same set of DJARDIR directories. Typically, all the AORs in a multi-region EJB server would share the same set of DJARDIR directories.
  6. CICS ignores any deployed JAR files in the pickup directory that have the same name and the same date and time stamps as currently-installed DJAR resources. A deployed JAR file with the same name but a later date-and-time stamp than an installed DJAR is treated as an update.
  7. Deleting a previously-installed deployed JAR file from the pickup directory does not remove the DJAR resource from CICS; its beans are still available. To make the beans unavailable, you must discard the DJAR resource.
  8. You cannot update a statically-installed DJAR definition by means of the scanning mechanism—you must first discard the static definition. For example, if you have a statically-installed DJAR definition named myDjar1, you cannot update it by scanning a deployed JAR file named myDjar1.jar.
  9. An invalid deployed JAR file is not detected early (when the pickup directory is scanned), but when the EJB environment attempts to open it. The DJAR resource for an invalid JAR file becomes UNRESOLVED. CICS outputs a message to indicate what is wrong with the JAR file. The message is sent to the CICS log and to the “EJB event” user-replaceable program.
  10. After every scan of the pickup directory, CICS outputs a message indicating the number of new and the number of updated deployed JAR files found during the scan.
GROUP(groupname)
Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.
Acceptable characters:
A-Z 0-9 $ @ #
Any lower case characters you enter are converted to upper case.

The GROUP name can be up to eight characters in length. Lowercase characters are treated as uppercase characters. Do not use group names beginning with DFH, because these characters are reserved for use by CICS.

HOST(hostname)
specifies the TCP/IP host name, or a string containing the dotted-decimal TCP/IP address, of this logical EJB/CORBA server.
Acceptable characters:
A-Z a-z 0-9 . -
For information about entering mixed case information, see Entering mixed case attributes.

The host name is included in Interoperable Object References (IORs) exported for objects in this logical server. Clients must use this host name to access the CICS listener regions.

If you are using connection optimization by means of Domain Name System (DNS) registration, to balance client connections across the listener regions of your logical IIOP or EJB server, specify the generic host name to be quoted by client connection requests. (The generic host name is the DNSGROUP value defined in the TCPIPSERVICE resource definition, suffixed by the name of the domain or subdomain managed by the MVS™ system name server. This is established by your MVS TCP/IP system administrator.) See Java™ Applications in CICS for more information about using DNS with IIOP and enterprise beans.

JNDIPREFIX(prefix)
specifies a JNDI prefix of up to 255 characters which is used when enterprise beans are published to the Java Naming and Directory Interface (JNDI). Start of change
Acceptable characters:
A-Z a-z 0-9 . / _ # @
For information about entering mixed case information, see Entering mixed case attributes.
End of change

Publishing a bean means binding a reference to the home of the bean in a name space. The naming context in which the bean is bound is named, relative to the initial context defined for the CICS region, using a concatenation of the JNDIPREFIX attribute of the CorbaServer and the name of the bean. The JNDIPREFIX attribute must match the prefix specified by the client when it uses JNDI to obtain a reference to the home interface for a bean. For more information, see Java Applications in CICS.

Note: Any JNDI sub-context below the CICS region's initial JNDI context may be transient. This is the case if CICS has write access to the initial context node (if you're using an LDAP name server) or initial context directory (if you're using a COS name server).

CICS creates the sub-context specified on the JNDIPREFIX option (if it has the necessary write permission and the sub-context does not already exist in the name space structure) when an enterprise bean is published from the CorbaServer. However, if all the enterprise beans in the CorbaServer are retracted, CICS may delete the sub-context from the name space structure. Where multiple CorbaServers share part of a prefix hierarchy, CICS never removes contexts that are still in use by any of them. But if the contexts in the prefix are empty they are removed, as far back as the initial context.

If you want to protect the sub-context hierarchy from deletion, do not give CICS write access to the initial context node or directory. (This means that you must create the top-level node or directory of the sub-context manually. For information on how to do this with an LDAP name server, see Java Applications in CICS.)

CICS limits the use of the / character in the JNDI prefix field to prevent the use of empty atomic components, which are denoted by an empty string. The / character may not be the first or last character of the prefix. Also, two or more consecutive instances of the / character are not allowed anywhere in the prefix.

If this option is not specified, no prefix is added when publishing enterprise beans to JNDI.

Start of changeOUTPRIVACYEnd of change
Start of changeThis attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.End of change
PORT
This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.
If this attribute is present in the CORBASERVER definition, the following attributes must be blank:
  • ASSERTED
  • BASIC
  • CLIENTCERT
  • SSLUNAUTH
  • UNAUTH
  • OUTPRIVACY
SESSBEANTIME({00,00,00|00,00,10|dd,hh,mm})
specifies, in days, hours, and minutes, the period of inactivity after which a session bean may be discarded by CICS.
00,00,00
Session beans will not be timed out.
00,00,10
Session beans may be discarded after ten minutes of inactivity. This is the default value.
dd,hh,mm
Session beans may be discarded after the specified period of inactivity. The maximum value you can specify is 99 days, 23 hours, and 59 minutes.
SHELF({/var/cicsts/|directory})
specifies the 1–255 character fully-qualified name of a directory (a shelf, primarily for deployed JAR files) on HFS. Start of change
Acceptable characters:
A-Z a-z 0-9 . / _ # @
For information about entering mixed case information, see Entering mixed case attributes.
End of change

CICS regions into which the CORBASERVER definition is installed must have full permissions to the shelf directory—read, write, and the ability to create subdirectories.

A single shelf directory may be shared by multiple CICS regions and by multiple CORBASERVER definitions. Each CICS region uses a separate subdirectory to keep its files separate from those of other CICS regions. The subdirectories for CORBASERVER definitions are contained within the subdirectories of the CICS regions into which they are installed. After a CICS region performs a cold or initial start, it deletes its subdirectories from the shelf before trying to use the shelf.

You should not modify the contents of a shelf that is referred to by an installed CORBASERVER definition. If you do, the effects are unpredictable.

SSL
This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.
If this attribute is present in the CORBASERVER definition, the following attributes must be blank:
  • ASSERTED
  • BASIC
  • CLIENTCERT
  • SSLUNAUTH
  • UNAUTH
  • OUTPRIVACY
SSLPORT
This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.
If this attribute is present in the CORBASERVER definition, the following attributes must be blank:
  • ASSERTED
  • BASIC
  • CLIENTCERT
  • SSLUNAUTH
  • UNAUTH
  • OUTPRIVACY
SSLUNAUTH(tcpipservice)
specifies the 8–character name of a TCPIPSERVICE that defines the characteristics of the port which is used for inbound IIOP with SSL but no client authentication. This attribute is optional. You cannot specify both the CLIENTCERT and SSLUNAUTH attributes.
Acceptable characters:
A-Z 0-9 $ @ #
Unless you are using the CREATE command, any lowercase characters you enter are converted to uppercase.
STATUS({ENABLED|DISABLED})
specifies whether the CorbaServer is to be installed in enabled or disabled state. The default is enabled.
UNAUTH(tcpipservice)
specifies the 8–character name of a TCPIPSERVICE that defines the characteristics of the port which is used for inbound IIOP with no authentication.
Acceptable characters:
A-Z 0-9 $ @ #
Unless you are using the CREATE command, any lowercase characters you enter are converted to uppercase.

Note that you must specify a value for the UNAUTH attribute when you define a CORBASERVER, even if you intend that all inbound requests to this CORBASERVER should be authenticated. This is because the PORTNUMBER attribute of the TCPIPSERVICE is required in order to construct IORs that are exported from this logical server.