# File Control Annotations

This section includes information on File control annotations.

## @jc:file Annotation

Specifies configuration attributes for a File control.

### Syntax

@jc:file

[directory-name="directory name"]
[file-mask="file name or file mask"]
[suffix-name="file name suffix"]
[suffix-type="timestamp or index"]
[create-mode="over-write or rename-old"]
[ftp-host-name="ftp host name"]
[ftp-username-name="ftp user name"]
[ftp-password="password"]
[ftp-password-alias="password alias"]
[ftp-local-directory="local directory name"]

@jc:file-operation

[io-type="read, readline, write or append"]
[file-content="file content description"]
[record-size="number of bytes per record"]
[encoding="character set encoding"]

### Attributes

These attributes determine the default behavior of the File control. The File control may be configured during its lifetime by calling methods of the FileContol class. To learn more about the FileControl class, see File Control Interface.

directory-name

A directory name is the absolute path name for the directory. In other words, it includes the drive specification as well as the path specification. For example, following are valid directory names:

C:\directory (Windows)

/directory (Unix)

\\servername\sharename\directory (Win32 UNC)

The directory-name attribute is required. Leaving the directory-name attribute unspecified results in an error.

file-mask

The file-mask attribute can specify either a file name or a file mask. If the file-mask contains a wild-card character (such as "*") it will be treated as a file mask. Typically, a wild-card character is specified to get the list of files in a directory. It is illegal to specify a wild-card character for any other operation.

File names are used for read, write and append operations.

suffix-name

This suffix will be used along with a timestamp or incrementing index for creating the file names. The default suffix-name will be "_". For example:

file_01, file_02, file_0809021230123

suffix-type

This option specifies if a timestamp or an incrementing index should be used as a suffix for the file names. The allowed options are: index and timestamp.

create-mode

This option specifies what needs to be done when a write operation is creating a new file and a file with the same name already exists. The allowed options are: over-write and rename-old.

ftp-host-name

This option specifies the name of the FTP host, for example, ftp://ftp.bea.com.

ftp-user-name

This option specifies the name of the FTP user.

ftp-password

This option specifies the FTP user's password. If you specify this attribute, you cannot specify the ftp-password-alias attribute.

ftp-password-alias

This option specifies the alias for a user's password. The alias is used to look up a password in a password store. If you specify this attribute, you cannot specify the ftp-password attribute.

ftp-local-directory

This option specifies the directory used for transferring files between the remote file system and the local file system. When reading a remote file, the file is copied from the remote system to the local directory and then read. Similarly, when writing to a remote file system, the file is written to the local directory and then copied to the remote system.

io-type

This attribute specifies the type of operation. The valid values are: read, readline, write, and append.

file-content

This option specifies a description of the contents of the file.

record-size

This option is used with methods of type @jc:file-operation io-type="readline". The record size, a positive integer, is expressed in bytes.

The record-size attribute is valid for methods with a return type of RawData and String, but not XmlObject. If this attribute is not specified, the default platform-specific line delimiters, such as carriage returns or line feeds, are used.

The following code illustrates the use of the record-size attribute:

/**
* @jc:file-operation io-type="readline" record-size="80"
*/
RawData readLine();

encoding

This option is used to specify the character set encoding for the file. The file type must be String or XMLObject. This option can not be used if large files are being processed.

Related Topics

File Control Interface

File Control