Association elements

As described in the topic "Resource associations part," the resource associations part is composed of association elements. Each element is specific to a file name (identified by the fileName property) and contains a set of entries, each with the following properties:
The values of the system and fileType properties determine what additional properties are available to you from the following list: You can find more information on cross-referencing record and file types in the topic File types.

commit

Indicates (for an EGL-generated COBOL program on iSeries®) whether to enable commitment control.

Select one of these values:

NO (the default)
Use of sysLib.commit or sysLib.rollback has no effect.
YES
You can use sysLib.commit and sysLib.rollback to define the end of a logical unit of work.

conversionTable

Specifies the name of the conversion table used by a generated Java™ program during access of either of the following kinds of resources:
  • A WebSphere® MQ message queue.
  • A serial file that is related to an EGL CSV record.

duplicates

Specifies (for an EGL-generated COBOL program on iSeries®) whether an accessed VSAM file is allowed to contain duplicate keys.

Select one of these values:

NO (the default)
No duplicate keys are allowed.
YES
The VSAM file is allowed to contain duplicate keys.

The value of duplicates must be consistent with the use of the keyword UNIQUE in the data description specification (DDS) that describes the physical file on iSeries®. If the value of duplicates is YES, for example, you must not specify UNIQUE.

The next table shows the consequence of an inconsistency in the two values.

DDS keyword Value of duplicates in the association element COBOL return code after a file open EGL return code after a file open EGL I/O error value
UNIQUE YES 95 00000220 invalidFormat
no UNIQUE NO 95 00000220 invalidFormat

fileName

Refers to a logical file name, as specified in one or more records. You are creating an association element that relates this name to a physical resource on one or more target systems. For print output, specify the value printer.

You can use an asterisk (*) as a global substitution character in a logical file name; however, that character is valid only as the last character. See Resource associations part for more details on using the asterisk as a wild card.

fileType

Specifies the file organization on the target system. You can select an explicit type like seqws. Alternatively, you can select the value default, which is itself the default value of the fileType property. Use of the default means that a file type is selected automatically:
  • For a particular combination of target system and EGL record type.
  • For print output, when the file name is printer.

To find information on fileType values, along with defaults, refer to the table in the section "Valid file types of target runtime environment" of the topic Resource associations part.

formFeedOnClose

Indicates whether a form feed is issued when the output of a print form ends. (A print form is produced when your code issues a print statement.)

This property is available only if the fileName value is printer in one of the following cases:
  • The system value is aix, iSeriesj, linix, or linux, and the fileType value is seqws or spool; or
  • The system value is win, and the fileType value is seqws.
Select one of these values:
YES
A form feed occurs (the default).
NO
A form feed does not occur.

includeRecordLengthField

Indicates whether to write the Record Length field for variable-length sequential records (fileType seqws only).

Select one of these values:
YES (the default)
The record is prefixed with a field that specifies the length of the record.
NO
The length of the record is not written with the record. To read back the record, you must specify the record length in the variable specified by the lengthItem attribute in your EGL record.

pcbName

Specifies the name of the PCB record that is used to access an IMS™ message queue or GSAM database. The entry is used only in these cases:
  • You are generating COBOL code; and
  • The target system is one of these:
    • imsvs (in which case the PCB record may be of type IO_PCBRecord or ALT_PCBRecord)
    • imsbmp (in which case the PCB record may be of type IO_PCBRecord, ALT_PCBRecord, or GSAM_PCBRecord)
    • zosbatch (in which case the PCB record must be of type GSAM_PCBRecord)

replace

Specifies whether adding a record to the file replaces the file rather than appending to the file. This entry is used only in these cases:
  • You are generating Java™ code; and
  • The fileType of the file is seqws.
Select one of these values:
NO (the default)
Append to the file.
YES
Replace the file. The first add statement for the serial file in the program, or the first add statement for the serial file after a close statement, adds the data to the beginning of the serial file, replacing all the previous contents.

system

Specifies the target platform. Select one of the following values:
aix
AIX®
imsbmp
IMS™ BMP
imsvs
IMS/VS
hpux
HP-UX
iseriesc
iSeries® COBOL
iseriesj
iSeries®Java™
linux
Linux™ (Intel™ hardware)
solaris
Solaris
uss
z/OS®UNIX™ System Services
win
Windows™ 2000/NT/XP
zlinux
Linux™ (zSeries® hardware)
zosbatch
z/OS® batch
zoscics
CICS® for z/OS®
any
Any target platform

systemName

The systemName property specifies the system resource name of the file or data set associated with the EGL file name. Enclose the name in single or double quote marks if it contains a space or any of the following characters: 
  % = , ( ) /

The value of the systemName property depends on the values of the system and fileType properties, as described in the following sections. To see this information in table form, see Record and file type cross-reference.

You can dynamically change the value of systemName at runtime by setting one of the following system variables:
  • For serial, indexed, relative, or WebSphere® MQ records, set the recordName.resourceAssociation variable. EGL uses the systemName property to initialize the value of the recordName.resourceAssociation. When there is I/O for a record and the recordName.resourceAssociation has been changed, EGL automatically closes the previously opened file before opening the file in recordName.resourceAssociation.
  • For print output, set the converseVar.printerAssociation variable. EGL uses the systemName property to initialize the value of converseVar.printerAssociation. For certain runtime environments and file types, multiple print files can be open simultaneously.

systemName for debugging

The debugger runs only in the Windows™ and Linux™ environments. Therefore you must set the system property to either win or linux, depending the platform where you are running the debugger, and set the fileType and systemName properties accordingly.

systemName in Java™ environments

The following sections describe the possible values for systemName in various Java™ environments.

systemName for AIX®

When the system property is set to aix, the following values are available for the fileType property:
ibmcobol
The value of the systemName property is the name of a VSAM file that is associated with an EGL serial, indexed, or relative record. The VSAM file must be on the same AIX® machine where the program is running.
mq
The value of the systemName property is the name of an WebSphere® MQ message queue associated with an EGL MQRecord. The default value is the EGL queue name. The value of systemName is in the form of either queueName or queueManagerName:queueName. If the systemName is queueName, EGL connects to the default queue manager.
seqws
The value of the systemName property is the name of a file that is associated with an EGL serial record.
spool
The value of the systemName property is set to the name of a printer or the path to a spool file associated with an EGL print file. The default value for systemName is the default printer for the system.

systemName for iSeries® Java™

When the system property is set to iseriesj, the following values are available for the fileType property:
mq
The value of the systemName property is the name of a WebSphere® MQ message queue associated with an EGL MQRecord. The default value is the EGL queue name. The value of systemName is in the form of either queueName or queueManagerName:queueName. If the systemName is queueName, EGL connects to the default queue manager.
seqws
The value of the systemName property is the name of a file that is associated with an EGL serial record.
spool
The value of the systemName property is set to the name of a printer or the path to a spool file associated with an EGL print file. The default value for systemName is the default printer for the system.

systemName for Windows™

When the system property is set to win, the following values are available for the fileType property:
ibmcobol
The value of the systemName property is the name of a remote VSAM file that is associated with an EGL serial, indexed, or relative record. The remote VSAM file must be located on z/OS®. The file name must be in the following format:
\\machineName\qualifier.fileName
machineName
The SNA LU alias name as specified in the SNA configuration.
qualifier.fileName
The VSAM data set name, including a qualifier.
mq
The value of the systemName property is the name of an WebSphere® MQ message queue associated with an EGL MQRecord. The default value is the EGL queue name. The value of systemName is in the form of either queueName or queueManagerName:queueName. If the systemName is queueName, EGL connects to the default queue manager.
seqws
The value of the systemName property is the name of a file that is associated with an EGL serial record.

systemName for other Java™ platforms

The following values of the system property all have the same possible values as the fileType property:
  • hpux
  • linux
  • solaris
  • uss
  • zlinux

For any of these system values, the following values are available for the fileType property:

mq
The value of the systemName property is the name of an MQ message queue associated with an EGL MQRecord. The default value is the EGL queue name. The value of systemName is in the form of either queueName or queueManagerName:queueName. If the systemName is queueName, EGL connects to the default queue manager.
mq topic

The value of the systemName property is the name of an MQ topic name associated with an EGL MQRecord. No default values are considered. The value of systemName is in the form of below format,

queueManagerName:queueName:topicString:

queueManagerName::topicString:

queueManagerName:queueName::topicName

queueManagerName:::topicName queueManagerName

QueueManagerName, and Topic name or Topic string are mandatory. EGL will not connect to the default queue manager.

seqws
The value of the systemName property is the name of a file that is associated with an EGL serial record.
spool
The value of the systemName property is set to the name of a printer or the path to a spool file associated with an EGL print file. The default value for systemName is the default printer for the system.

systemName in COBOL environments

The following sections describe the possible values for systemName in various COBOL environments.

systemName for IMS™ BMP

When the system property is set to imsbmp, EGL supports the same values for the fileType property that it supports in either IMS/VS or z/OS® batch.

systemName for IMS/VS

When the system property is set to imsvs, the following values are available for the fileType property:
mq
The value of the systemName property is the name of a WebSphere® MQ message queue associated with an EGL MQRecord. The default value is the EGL queue name.
mmsgq
The value of the systemName property is the name of a logical terminal or transaction code associated with the message queue. The EGL file must be a serial file. The default value for systemName is the EGL file name.
smsgq
The value of the systemName property is the name of a logical terminal or transaction code associated with the message queue. The EGL file must be a serial or a print file. For serial files, the default value for systemName is the EGL file name. For print output, the default is printer.

systemName for iSeries® COBOL

When the system property is set to iseriesc, the following values are available for the fileType property:

mq
The value of the systemName property is the name of a WebSphere® MQ message queue associated with an EGL MQRecord. The default is the EGL queue name.
seq
For serial files, the value of the systemName property is the name of a system sequential file associated with an EGL serial or print file. The value must be an unqualified file name, with a maximum size of 10 bytes. EGL uses the runtime library list (*LIBL) and the first member in the physical or logical file to complete qualification of the file name. Override Database File commands can be used prior to run time to specify a different file. The default systemName is the EGL file name. Override Printer File commands can be used prior to run time to specify a different print file.
Note:
For print output, the value is the same as for spool, except that the seq value for fileType inserts a page eject at the end of the print stream when the file is closed.
spool
The value of the systemName property is the name of a printer file object (*PRTF) associated with an EGL print file. For example, QVGNPRTF is the name of a printer file object that is shipped with the EGL runtime product for iSeries®. Output is sent to the output queue for the job as a spooled file. The value of systemName must be an unqualified file name, with a maximum size of 10 bytes. The runtime library list (*LIBL) is used to complete qualification of the file name. Override Printer File commands can be used prior to run time to specify a different file. The default systemName is QVGNPRTF.
Note:
For printer files, seq and spool differ in that seq inserts a page eject at the end of the print stream when the file is closed.
vsam
For EGL serial files, the value of the systemName property is the name of a system sequential file. For EGL indexed files, systemName is the name of a system indexed file. Defaults are the same as those for the seq value of the fileType property.

systemName for z/OS® batch

When the system property is set to zosbatch, the following values are available for the fileType property:

gsam
The value of the systemName property is the data set name for a GSAM file that is associated with an EGL serial or print file. For serial files, the default value for systemName is the EGL file name. For print output, the default is printer; but if you are sharing an output file with a program generated in VisualAge® Generator, specify EZEPRINT instead.
mq
The value of the systemName property is the WebSphere® MQ message queue name associated with an EGL MQRecord. The default is the EGL queue name.
seq
The value of the systemName property is the name of a z/OS® sequential file that is associated with an EGL serial or print file. EGL generates COBOL READ/WRITE statements to gain access to the file. Do not set fileType to seq when you use dynamic allocation, recordName.resourceAssociation, or converseVar.printerAssociation.
For serial files, EGL uses the file name as the DD name and the systemName as the data set name (DSN) in the generated sample runtime JCL. For print files, EGL uses EZEPRINT as the DD name and does not use the systemName property in the generated sample runtime JCL.
For serial files, the default value for systemName is the EGL file name.
seqrs
The value of the systemName property is the name of a z/OS® sequential file that is associated with an EGL serial or print file. EGL generates calls to host services for all reads and writes to the file. Set fileType to seq when you are using dynamic allocation, recordName.resourceAssociation, or converseVar.printerAssociation.
For serial files, EGL uses the file name as the DD name and the systemName as the data set name (DSN) in the generated sample runtime JCL. For print files, EGL uses EZEPRINT as the DD name and does not use the systemName in the generated sample runtime JCL.

Multiple print files can be open simultaneously.

If you want to share a print file between a program generated with EGL and a program generated with VisualAge® Generator, you cannot rely on default values, but must create a resource association such that the value of fileName is printer and the value of systemName is EZEPRINT.

vsam
The value of the systemName property is the name of a VSAM file that is associated with an EGL serial, indexed, or relative file. EGL generates COBOL READ/WRITE statements to gain access to the file. Do not set fileType to vsam when you use dynamic allocation, recordName.resourceAssociation, or the EGL get previous statement.
EGL uses the file name as the DD name and the systemName as the data set name (DSN) in the generated sample runtime JCL.
The default value for systemName is the EGL file name.
vsamrs
The value of the systemName property is the name of a VSAM file that is associated with an EGL serial, indexed, or relative file. EGL generates calls to host services for all reads and writes to the file. Set fileType to vsamrs when you use dynamic allocation, recordName.resourceAssociation, or the EGL get previous statement.
EGL uses the file name as the DD name and the systemName as the data set name (DSN) in the generated sample runtime JCL.
The default value for systemName is the EGL file name.

systemName for CICS® for z/OS®

When the system property is set to zoscics, the following values are available for the fileType property:
mq
The value of the systemName property is the name of a WebSphere® MQ message queue associated with an EGL MQRecord. The default value is the EGL queue name.
spool
The value of the systemName property is the name of a JES SPOOL file associated with an EGL serial or print file. For serial files, the default name is the EGL file name. For print output, the default is printer.
Input file name: userid.class
The userid parameter is a 4- to 8-character external writer name, or an asterisk (*). CICS® requires that the first four characters of the external writer name be the same as the first four characters of the CICS® APPLID used to identify the CICS® region to ACF/VTAM. The class parameter is a one-character spool class. The class parameter is optional and defaults to "A". The maximum name size is 10 bytes. Refer to the CICS® customization manual for more information.
Output file name: nodeid.userid.class
The nodeid parameter is either a 1- to 8-character system node ID, or an asterisk (*). The userid parameter is a 1- to 8-character system user ID, or an asterisk (*). The class parameter is a one-character spool class. The class parameter is optional and defaults to "A". If class is not specified, userid is also optional, and defaults to the CICS® user ID (the same value stored in sysVar.userID). The maximum name size is 19 bytes. Refer to the CICS® customization manual for more information.
Multiple printer files can be open simultaneously.
tempmain
The value of the systemName property is an 8-byte queue name for a main temporary storage queue associated with an EGL relative or serial file. The default is the EGL file name. Some queue names are reserved for use by EGL and are prefixed by the letters "EZE".
tempaux
The fileType of tempaux is like tempmain, except that it identifies an auxiliary temporary storage queue.
transient
The value of the systemName property is a 4-byte DCT name for a transient data queue associated with an EGL serial or print file. For serial files, the default is the first 4 characters of the EGL file name. For print output, the default is printer. The transient data queue name must be defined to CICS® using an RDO TDQUEUE entry.
Multiple printer files can be open simultaneously.
vsam
The value of the systemName property is an 8-byte file name for a VSAM file associated with an EGL indexed, relative, or serial file. The file name must be defined to CICS® using an RDO FILE entry.

text

When accessing a file by means of a serial record, the text property specifies whether a generated Java™ program should do the following :
  • Append end-of-line characters during the add operation. On non-UNIX platforms, those characters are a carriage return and line feed; on UNIX™ platforms, the only character is a line feed.
  • Remove end-of-line characters during the get next operation.
Select one of these values:
NO (the default)
Do not append or remove the end-of-line characters.
YES
Make the changes. This is useful if the generated program exchanges data with products that expect records to end with the end-of-line characters.