Configuring Associations and Switches

P3/COBOL has an extremely flexible and powerful facility for configuring the subsystems that are used by the application to interface with the non-COBOL application resources. This is done through associations and sub-elements of them defined in the runtime configuration for the application. While each type of association has structure and options specific to the resource type they manage, there are some common capabilities shared by most of them.

Replacement Markers

In many of the association option elements and attributes described here, a facility for replacing strings or portions of strings with dynamically determined strings is permitted. The are called replacement markers, and they are introduced by a { and terminated by a }. Between the delimiters, there are several possible choices. If a pattern has been used in the association (for example, a name-pattern), you may use a positive integer that refers to a capture group resulting from the pattern that was matched. More information on this may be found at regex101.com.

If the referenced capture group exists, its value will replace the marker in the attribute being evaluated. Alternatively, you may use the name of a parameter, Java runtime property, or environment variable, in which case the value of the parameter, property, or variable will replace the marker. If none of these are the case, or if the group or property is not defined in the current context, the actual marker content string will be used as the literal value to replace the marker. The search from left to right continues until one of these replacements can be made, or the end of the subject string is reached. When a replacement is made, the subject string (the one being processed for replacement) is then reevaluated from the beginning to determine the next marker, if any, to replace. This process is repeated until the end of the subject string is reached. During the processing, several markers could be processed, and they may be nested, allowing complex substitutions to be made.

For example,

now is {the.time}pm, {{ALL_PROPERTY_NAME}} {2} will come to the aid of {{1}} country

If there is a Java property named the.time with a value of "1300", an environment variable named ALL_PROPERTY_NAME with a value of "the.time", and a pattern of:

^.*?([0-9]+).*?(good men).*?(their).*?$

previously matching a string:

"there are 3 extremely good men and you are waiting for their help", the subject string would be transformed into:

now is 3pm, 3 good men will come to the aid of their country.

Additionally, it is possible to force the result of a substitution to upper or lower-case characters by use of either {u: ... } or {l: ... } respectively. The "u" and "l" are known as replacement modifiers. Using this technique allows the Micro Focus DD_ filename behavior to be mimicked. For example, an external name of {DD_{u:0}} when given a file name of "myfile" and pattern .* will resolve to the value of the environment variable DD_MYFILE at the time the pattern is matched.

Finally, it is possible to override a configured parameter or environment variable with a client-specified value by including a c replacement modifier in the prefix. For example {c:CLIENT_PATH} would use a proxy value for the parameter named "client path" if it is supplied by a remote client. Otherwise, it would use the value as determined by the actual runtime configuration file or environment.

💡

One further wrinkle, any \ characters within a capture group replacement marker are replaced by / characters. This permits either form of file path separator to be used in associations since the external name is to be processed as a Java path, and Java knows how to work properly with whatever environment it is running in.

Parameters

In some cases, it is desirable for the configuration file to contain marker variables that are neither Java properties nor environment variables, but rather just variables local to the configuration file. Such variables are called "parameters" and are defined in a parameters option element.

Within the <parameters> element, one or more <parameter> elements may be included. Each one defines the value of a configuration parameter for the current runtime configuration. Each element has a name and value attribute which defines the name and value of the parameter being defined. Note that the value of a parameter may itself include replacement markers.

Checkout the parameters runtime option for more details.

File Associations

P3/COBOL can support any number of different file systems serving a running program. Furthermore, the association between a particular file instance and a serving file system is established at the time the file is OPEN ed. This runtime association is controlled by the file-associations element of the (runtime.p3c) configuration file.

Within the <file-associations> element, one or more <file-association> elements may be included. Each one defines the conditions for using a particular file system (or file connector) at the time a file is opened.

Association matching occurs dynamically whenever a file is opened. The association definitions themselves, however, are part of the initialized runtime configuration and are immutable once the runtime is initialized. Complete all programmatic changes to file associations—including nested volume, migration, device, and remote-server options—before supplying the runtime options to a runtime component. Rather than modifying options at runtime, define multiple associations with distinct name-pattern values so that the desired options are selected as a function of the file name. See Selecting Volume Configuration by File Name for a worked example.

An optional appliesTo attribute on the file-association may be used to restrict the application of that file association to one or more file organizations. The valid value of this attribute is a space-separated list of one or more of the following: SEQUENTIAL, RELATIVE, INDEXED.

An optional listenFrom attribute on the file-association may be used to specify the class name of a file and/or storage manager listener to be associated with the selected files. The valid value of this attribute is a full Java class name of the listener to be configured, whose class file is available on the program's class path.

An optional boolean pipe attribute determines if the external name (see below) refers to a piped connection rather than a file.

Each file-association also may have some or all of the following elements:

Option	Description
`<name-pattern>`	This element contains a string comprising a regular expression1 used to select file names that use this association. If the file name being opened matches this pattern, this file association determines the file connector to be used to open the file, and to perform any subsequent operations until the file is closed. Once the file is closed, a subsequent open may select the same file association or a different one depending on the file name at that time. This pattern will establish the capture groups for this association.
`<external-name>`	This element contains a string comprising a mapping of the matched name-pattern to a file path within the associated file system. It can be a simple string path that will replace the file assignment name that matched the pattern, or it can be a string with replacement markers within it. In the latter case, the string would include one or more markers usually referring to capture groups from the name-pattern. For example, to add a directory prefix to an assignment name you could use “files/0” as the external-file-name element. In this case, group 0 refers to the entire matched pattern, and the external file path would be the assignment name within the “files” directory under the current working directory. The actual use of the resulting external name is dependent on the file connector type that is used to access the file. Sequential and Relative organization files use the external name to specify the Java path by which the file may be opened. Indexed files using the built-in MVCC file system use the external name to identify the file within the physical volume used to store the file(s). For sequential organization files, if the `pipe` attribute is true, this element may contain a shell command to be used as the source/sink of a pipe to be read/written instead of a file, or it may contain the name of an existing pipe if a "\|" character is the first character of the element.
`<connector-class>`	This element contains a string that determines the class name of the file connector to be used. This string can be either of two forms. If it consists of a package name followed by “.” the “” will be replaced by a standard connector class name for the file organization being opened, and that string will be used as the class name of the connector. If the connector-class string does not end in “.*” the entire string will be assumed to be the class name for the file connector. In either case the connector class chosen must implement the interface(s) required by the file organization being opened. This may be used to specify the EXTFH indexed organization file connector, for example.
`<external-handler-name>`	This element contains a string that is used when the file connector is an external (native) file handler such as C-Tree’s ACE for COBOL file handler. The string is used to identify the external handler from within the selected file connector.
`<record-lock-time-limit>`	This element contains a string that is used to determine the maximum time that a program may hold a lock on a record. If a record lock is attempted and another file connector is holding a lock established more than this value of milliseconds previous, the lock will be broken and the present lock applied. The original lock holder will be notified via exception when/if is attempts to update or delete the previously locked record. See Record locking for more information.
`<device-configuration>`	This element contains information that can be used to configure the use of sequential organization files that refer to devices or other platform-dependent capabilities that can be accessed sequentially. See Associating Files With Devices for more information.
`<volume-configuration>`	This element contains options regarding the independently-managed file clusters (volumes) containing the indexed organization files in the association. See Associating Files With Volumes for more information.
`<remote-server-configuration>`	This element contains options regarding the use of a remote file server for the files in the association. See Multi-JVM File Sharing for more information.
`<migration-configuration>`	This element contains options to control the migration of exisiting data files to the standard P3/COBOL data file formats. See File Migration for more information.

An example of a complete file association element would be:

runtime.p3c

<file-association appliesTo="INDEXED">
    <name-pattern>ctreefile</name-pattern>
    <connector-class>com.turrettech.p3cobol.lib.extfh.*</connector-class>
    <external-handler-name>CTEXTFH</external-handler-name>
</file-association>

In this example, any file opened with a name of ctreefile would use the standard connector class located in the package path indicated and that class would call the CTEXTFH external library entry point to service requests for that file.

Program Associations

The association between a particular P3/COBOL program Java class and the name specified in the CALL COBOL statement can be controlled by the program-associations element of the (runtime.p3c) configuration file.

Within the <program-associations> element, one or more <program-association> elements may be included. Each one defines the conditions for using a particular (Java) program class name at the time a program is CALLed. Each program-association has the following elements:

Option Description

<name-pattern> This element contains a string comprising a regular expression used to select program names that use this association. If the program name being CALLed matches this pattern, this program association determines the Java class to be used to instantiate the program, if the program has not previously been loaded. Once the program is instantiated, subsequent CALLs to the same name will refer to this instantiaion.

<class-name> This element contains a string comprising a mapping of the matched name-pattern to a Java class name It can be a simple string path that will replace the program name that matched the pattern, or it can be a string with selected portions of the matched program name embedded within it. In the latter case, the string would include one or more “capture groups” from the name-pattern by including the group index within braces. For example, to add a package prefix to a program name you could use “org.tempuri.programs.0” as the class-name element. In this case, group 0 refers to the entire matched pattern, and the Java class name would include the indicated package name prefix.

Option	Description
`<name-pattern>`	This element contains a string comprising a regular expression used to select program names that use this association. If the program name being CALLed matches this pattern, this program association determines the Java class to be used to instantiate the program, if the program has not previously been loaded. Once the program is instantiated, subsequent CALLs to the same name will refer to this instantiaion.
`<class-name>`	This element contains a string comprising a mapping of the matched name-pattern to a Java class name It can be a simple string path that will replace the program name that matched the pattern, or it can be a string with selected portions of the matched program name embedded within it. In the latter case, the string would include one or more “capture groups” from the name-pattern by including the group index within braces. For example, to add a package prefix to a program name you could use “org.tempuri.programs.0” as the class-name element. In this case, group 0 refers to the entire matched pattern, and the Java class name would include the indicated package name prefix.

An example of a complete program association element would be:

runtime.p3c

<program-association>
    <name-pattern>([^.])*[.]COB$</name-pattern>
    <class-name>{1}</class-name>
</program-association>

In this example, any program CALLed with a name ending in .COB would refer to a program class derived from the string prior to the .COB. All of the normal munging of the program name to derive the class name would take place using the result of the mapping, which in this case would be the string prior to the .COB suffix.

Database Associations

P3/COBOL supports access to relational database systems providing a JDBC API both through the standard file system indexed organization files and through the its built-in embedded SQL capability (ESQL). This database association is controlled by the database-associations element of the (runtime.p3c) configuration file.

Within the <database-associations> element a <database-association> element may be included. This element defines the JDBC parameters necessary to establish a connection with a specific database instance. Each database-association has some or all of the following elements:

Option	Description
`<user-name>`	This element contains the user name to be used to connect to the JDBC database connector.
`<password>`	This element contains the password to be used to connect to the JDBC database connector.
`<host>`	This element contains the host name to be used to locate the JDBC database instance.
`<driver>`	This element contains the class name of the JDBC driver to be used to access the JDBC database connector.
`<jdbc-connection-override>`	If present, this element provides a class name which overrides the standard JdbcConnector class. This permits a user-written Java class to provide the JDBC connection rather than the standard connector using the options in this section.

An example of a database association that provides a connection to a MySQL database server is:

runtime.p3c

<database-associations>
    <database-association>
        <driver>com.mysql.jdbc.Driver</driver>
        <host>jdbc:mysql://localhost:3306/mysqldb</host>
        <user-name>myuserid</user-name>
        <password>mypassword</password>
    </database-association>
</database-associations>

An example of a database connection to the built-in (h2) database would be:

runtime.p3c

<database-associations>
    <database-association>
        <driver>org.h2.Driver</driver>
        <host>jdbc:h2:~/mydatafiles</host>
        <user-name>sa</user-name>
        <password></password>
    </database-association>
</database-associations>

Any JDBC driver jars must be included in the classpath used to execute the P3/COBOL program, except for the built-in H2 driver included in the p3cobol.jar.

Switch Settings

In order to provide external switch settings to a P3/COBOL program that uses switches, the switch-settings option element is used. Within the switch-settings element, one or more switch elements determine the settings of external switches when the program is run. Each switch element has two elements:

Option Description

<name> This element contains the name of the switch referred to in the P3/COBOL program(s). Any valid switch name may be used (e.g., switch-0, switch-1, etc.).

<setting> This element contains the initial setting of the named switch. The choices are: OFF, ON, WIRED_OFF, WIRED_ON, NC. ON and OFF set the initial switch to the described condition. WIRED-ON and WIRED-OFF set the switch to the described condition, and the switch may not be changed by the COBOL program. NC indicates no connection with the program (i.e., the switch is controlled entirely by the program and the initial state is undefined).

Option	Description
`<name>`	This element contains the name of the switch referred to in the P3/COBOL program(s). Any valid switch name may be used (e.g., switch-0, switch-1, etc.).
`<setting>`	This element contains the initial setting of the named switch. The choices are: OFF, ON, WIRED_OFF, WIRED_ON, NC. ON and OFF set the initial switch to the described condition. WIRED-ON and WIRED-OFF set the switch to the described condition, and the switch may not be changed by the COBOL program. NC indicates no connection with the program (i.e., the switch is controlled entirely by the program and the initial state is undefined).

See Setting Switches for more information.

Indexed File System Associating Files With Devices