OPEN statement

Syntax

OPEN [dict,] filename [TO file.variable] [ON ERROR statements]
{THEN statements [ELSE statements] | ELSE statements}

Description

Use the OPEN statement to open an InfoSphere® DataStage® file for use by BASIC programs. All file references in a BASIC program must be preceded by either an OPEN statement or an OPENCHECK statement for that file. You can open several InfoSphere DataStage files at the same point in a program, but you must use a separate OPEN statement for each file.

dict is an expression that evaluates to a string specifying whether to open the file dictionary or the data file. Use the string DICT to open the file dictionary, or use PDICT to open an associated Pick-style dictionary. Any other string opens the data file. By convention an empty string or the string DATA is used when you are opening the data file. If the dict expression is omitted, the data file is opened. If dict is the null value, the data file is opened.

filename is an expression that evaluates to the name of the file to be opened. If the file exists, the file is opened, and the THEN statements are executed; the ELSE statements are ignored. If no THEN statements are specified, program execution continues with the next statement. If the file cannot be accessed or does not exist, the ELSE statements are executed; any THEN statements are ignored. If filename evaluates to the null value, the OPEN statement fails and the program terminates with a run-time error message.

Use the TO clause to assign the opened file to file.variable. All statements that read, write to, delete, or clear that file must refer to it by the name of the file variable. If you do not assign the file to a file variable, an internal default file variable is used. File references that do not specify a file variable access the default file variable, which contains the most recently opened file. The file opened to the current default file variable is assigned to the system variable @STDFIL.

Default file variables are not local to the program from which they are executed. When a subroutine is called, the current default file variable is shared with the calling program.

When opening an SQL table, the OPEN statement enforces SQL security. The permissions granted to the program's effective user ID are loaded when the file is opened. If no permissions have been granted, the OPEN statement fails, and the ELSE statements are executed.

All writes to an SQL table opened with the OPEN statement are subject to SQL integrity checking unless the OPENCHK configurable parameter has been set to FALSE. Use the OPENCHECK statement instead of the OPEN statement to enable automatic integrity checking for all writes to a file, regardless of whether the OPENCHK configurable parameter is true or false.

Use the INMAT function after an OPEN statement to determine the modulo of the file.

The ON ERROR Clause

The ON ERROR clause is optional in the OPEN statement. Its syntax is the same as that of the ELSE clause. The ON ERROR clause lets you specify an alternative for program termination when a fatal error is encountered while the OPEN statement is being processed.

If a fatal error occurs, and the ON ERROR clause was not specified, or was ignored (as in the case of an active transaction), the following occurs:

An error message appears.
Any uncommitted transactions begun within the current execution environment roll back.
The current program terminates.
Processing continues with the next statement of the previous execution environment, or the program returns to the command prompt.

A fatal error can occur if any of the following occur:

A file is not open.
file.variable is the null value.
A distributed file contains a part file that cannot be accessed.

If the ON ERROR clause is used, the value returned by the STATUS function is the error number.

The STATUS Function

The file type is returned if the file is opened successfully. If the file is not opened successfully, the following values might return:

Value: Description
-1: Filename not found in the VOC file.
-2^¹: Null filename or file.
-3: Operating system access error that occurs when you do not have permission to access an InfoSphere DataStage file in a directory. For example, this might occur when trying to access a type 1 or type 30 file.
-4¹: Access error when you do not have operating system permissions or if DATA.30 is missing for a type 30 file.
-5: Read error detected by the operating system.
-6: Unable to lock file header.
-7: Invalid file revision or wrong byte-ordering for the platform.
-8¹: Invalid part file information.
-9¹: Invalid type 30 file information in a distributed file.
-10: A problem occurred while the file was being rolled forward during warm-start recovery. Therefore, the file is marked "inconsistent."
-11: The file is a view, therefore it cannot be opened by a BASIC program.
-12: No SQL privileges to open the table.
-13¹: Index problem.
-14: Cannot open the NFS file.

¹A generic error that can occur for various reasons.

Examples

OPEN "SUN.MEMBER" TO DATA ELSE STOP "CAN'T OPEN 
SUN.MEMBER"
OPEN "FOOBAR" TO FOO ELSE STOP "CAN'T OPEN FOOBAR"
PRINT "ALL FILES OPEN OK"

This is the program output:

CAN'T OPEN FOOBAR

The following example opens the same file as in the previous example. The OPEN statement includes an empty string for the dict argument.

OPEN "","SUN.MEMBER" TO DATA ELSE STOP "CAN'T OPEN 
SUN.MEMBER"
OPEN "","FOO.BAR" TO FOO ELSE STOP "CAN'T OPEN 
FOOBAR"
PRINT "ALL FILES OPEN OK"