resourceAssociation variable for file I/O

When your program uses a record in an I/O operation, EGL assumes that the record-specific recordName.resourceAssociation variable contains the name of the physical file that holds the record (if that variable supports the particular type of file).

EGL initializes the variable in accordance with the ResourceAssociation part that is used at generation time; for more information, see the Resource associations part. You can change the object of your I/O operations at run time by placing a different value in the recordName.resourceAssociation variable.

In most cases, you must use the syntax recordName.resourceAssociation. If EGL can determine the record that you intended, you do not need to specify the recordName portion, as in each of the following cases:

I/O is only performed against one record in the program.
resourceAssociation is used in a function that performs I/O against only one record.
I/O is performed against multiple records in the program, but all records have the same file name; in this case, the first record that appears in an I/O statement is used as the implicit qualifier.

resourceAssociation has the following characteristics:

Primitive type: CHAR
Data length: 300 characters for Java™ generation and Debug, 65 characters for COBOL generation
Saved across segment?: Yes

Definition considerations

The value that you move into recordName.resourceAssociation must be a valid system resource name for the system and file type that you specified when the program was generated. If more than one record specifies the same file name and you modify resourceAssociation for any record with that file name, the value of resourceAssociation changes for all the records in the program that have the same file name.

A system resource that is identified in resourceAssociation is closed in the following circumstances:

An I/O option runs against a record that has the same EGL file name as the record that qualifies resourceAssociation.
The record variable is changed.

To close the file that is associated with the current setting of resourceAssociation, use a close statement. EGL automatically closes all open files when a run unit ends or a segmented converse occurs.

For COBOL environments, EGL folds the contents of resourceAssociation to uppercase before it uses those contents to access a file. However, the value that you place in resourceAssociation remains unchanged for comparison purposes.

Files shared across programs

If multiple programs share a system resource, each program must set resourceAssociation to refer to the same resource. If two programs in the same run unit access the same logical file, each program must set resourceAssociation to the same system resource name at generation time to ensure that both programs access the same system resource at run time.

If two programs use the same EGL file name, each of the record-specific resourceAssociation variables must contain the same value. Otherwise the previously opened system resource is closed when a new one is opened.

To ensure that the two programs use the same value, set the system resource name at generation or at run time:

At generation time: If two programs in the same run unit access the same logical file, specify the same system resource name for the logical file at generation to ensure that both programs access the same physical file at run time.
At run time: If you use recordName.resourceAssociation, each program that accesses the file must set resourceAssociation for the file. If two programs in the same run unit access the same logical file, each program must set resourceAssociation to the same system resource name to ensure that both programs access the same physical file at run time.

WebSphere® MQ records

The system resource name for WebSphere® MQ records defines the queue manager name and queue name. Specify the name in the following format:

  queueManagerName:queueName

queueManagerName: Name of the queue manager
queueName: Name of the queue

As shown, the names are separated with a colon. However, you can omit queueManagerName and the colon. The system resource name is the initial value for the record-specific resourceAssociation field and identifies the default queue that is associated with the record. For more information, see WebSphere MQ message queue access.

Compatibility


Platform	Issue
CICS® for z/OS®	SPOOL The value is the input or output file name for a JES SPOOL file that is associated with a serial file. Input file name: userid.class. The userid parameter is a 4 to 8-character external writer name or an asterisk (). If you use an external writer name, CICS® requires that the first four characters of the external writer name be the same as the first four characters of the CICS® APPLID that identifies the CICS® region to ACF/VTAM. The class parameter is a one-character spool class. class is optional and defaults to "A". The maximum name size is ten bytes. For more information, see the CICS® customization manual. 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 either a 1 to 8-character system user ID or an asterisk(). The class parameter is a one-character spool class. class is optional and defaults to "A". If class is not specified, userid is optional and defaults to the CICS® user ID (the value stored in sysVar.usrID). The maximum name size is 19 bytes. For more information, see the CICS® customization manual. TEMPMAIN The value is an 8-byte queue name for a main temporary storage queue that is associated with a relative or serial file. Some queue names are reserved for use by EGL and are prefixed with "EZE". When a temporary storage queue name is moved into the record-specific variable *recordName*.resourceAssociation, the queue is dynamically created, unless it already exists. Multiple users cannot share a single temporary storage queue file at the same time. A CICS® ENQ serializes access to the file the first time you reference that file in the program. The DEQ is issued when the program closes the file. TEMPAUX TEMPAUX is like TEMPMAIN, except that it is used for an auxiliary temporary storage queue. TRANSIENT A 4-byte DCT name for a transient data queue that is associated with a serial file. The transient data queue name must be defined to CICS®. VSAM An 8-byte FCT name for a VSAM file that is associated with an indexed, relative, or serial file.
IMS™ BMP	IMS™ BMP supports the same file types that are supported for IMS/VS in addition to those that are supported for z/OS® batch.
IMS/VS	MMSGQ Supported only for output. The value (an 8-byte logical terminal name or transaction code) is defined to the IMS™ system and is associated with a message queue that accepts multiple-segment messages. In the ResourceAssociation part that is used at generation time, the file name is associated with a modifiable alternate PCB or with a modifiable express alternate PCB. The value in resourceAssociation is not folded to uppercase. SMSGQ Supported only for output. The value (an 8-byte logical terminal name or transaction code) is defined to the IMS™ system and is associated with a message queue that accepts single-segment messages. In the ResourceAssociation part that is used at generation time, the file name is associated with a modifiable alternate PCB or with a modifiable express alternate PCB. The value in resourceAssociation is not folded to uppercase.
iSeries® COBOL	The fileType must be seq (sequential) or vsam. You can move the value to resourceAssociation in one of the following ways: LIB/FILE MEMBER Explicitly specify Library, File and Member LIB/FILE The first member in the file is used FILE MEMBER Uses LIBL to find the file FILE Uses LIBL to find the file and uses the first member in that file When you modify the value in resourceAssociation, the iSeries® OVRDBF command functions in the following manner: Closes the old file Performs an override to the new value Opens the new file The value set in resourceAssociation is propagated from the call level and is changed to all its subordinate call levels. The value is not propagated if the file was previously opened by the program.
MQSeries®	The system resource name for WebSphere® MQ records defines the queue manager name and queue name. Use the following format to specify the name: `queueManagerName:queueName` queueManagerName Name of the queue manager. queueName Name of the queue. As shown, the names are separated with a colon. However, queueManagerName and the colon can be omitted. The system resource name is used as the initial value for the record-specific resourceAssociation field and identifies the default queue associated with the record.
z/OS® batch	GSAM Not supported. SEQ Not supported. SEQRS The value is a 54-byte data set name or an 8-byte DD name for a system sequential file that is associated with a serial file. If a value has not been set for resourceAssociation for a file, the program first checks for a data set that has been pre-allocated using the logical file name as the DD name. Otherwise, EGL uses the system resource name that you specified at generation to access the file. When you move a data set name into resourceAssociation, the resource is dynamically allocated to the related record file name using an MVS™ supervisor call (SVC99). The allocation is done with the DISP option set to SHR, so the data set is rewritten each time it is opened for output. VSAM Not supported. VSAMRS The value is a 44-byte data set name or an 8-byte DD name for a VSAM file that is associated with an indexed, relative, or serial file. If no value has been set for resourceAssociation for a file, the program checks for a data set that has been preallocated using the logical file name as the DD name. Otherwise, EGL uses the system resource name that you specified at generation to access the file. When you move a data set name into resourceAssociation, the resource is dynamically allocated to the related record file name using an MVS™ supervisor call (SVC99). The allocation is done with the DISP option set to SHR, so the data set is written each time it is opened for output.

Example

The following example shows the assignment of a file to the resourceAssociation variable.

  if (process == 1)
    myrec.resourceAssociation = "myFile.txt";
  else
    myrec.resourceAssociation = "myFile02.txt";
  end