OPENSEQ statement

Syntax

OPENSEQ filename, record.ID TO file.variable [USING 
dynamic.array]
 [ON ERROR statements] [LOCKED statements]
 {THEN statements [ELSE statements] | ELSE statements}
OPENSEQ pathname TO file.variable [USING dynamic.array]
 [ON ERROR statements] [LOCKED statements]
 {THEN statements [ELSE statements] | ELSE statements}

Description

Use the OPENSEQ statement to open a file for sequential processing. All sequential file references in a BASIC program must be preceded by an OPENSEQ or OPENDEV statement for that file. Although you can open several files for sequential processing at the same point in the program, you must issue a separate OPENSEQ statement for each. See the READSEQ statement and WRITESEQ statements for more details on sequential processing.

Note: Performing multiple OPENSEQ operations on the same file results in creating only one update record lock. This single lock can be released by a CLOSESEQ or RELEASE statement.

The first syntax is used to open a record in a type 1 or type 19 file.

The second syntax specifies a path name to open a UNIX or DOS file. The file can be a disk file, a pipe, or a special device.

filename specifies the name of the type 1 or type 19 file containing the record to be opened.

record.ID specifies the record in the file to be opened. If the record exists and is not locked, 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 record or the file itself cannot be accessed or does not exist, the ELSE statements are executed; any THEN statements are ignored.

pathname is an explicit path name for the file, pipe, or device to be opened. If the file exists and is not locked, it is opened and the THEN statements are executed; the ELSE statements are ignored. If the path name does not exist, the ELSE statements are executed; any THEN statements are ignored.

If the file does not exist, the OPENSEQ statement fails. The file can also be explicitly created with the CREATE statement.

OPENSEQ sets an update record lock on the specified record or file. This lock is reset by a CLOSESEQ statement. This prevents any other program from changing the record while you are processing it.

If filename, record.ID, or pathname evaluate to the null value, the OPENSEQ statement fails and the program terminates with a run-time error message.

The TO clause is required. It assigns the record, file, or device to file.variable. All statements used to sequentially read, write, delete, or clear that file must refer to it by the assigned file variable name.

If NLS is enabled, you can use the OPENSEQ filename, record.ID statement to open a type 1 or type 19 file that uses a map defined in the .uvnlsmap file in the directory containing the type 1 or type 19 file. If there is no .uvnlsmap file in the directory, the default mapname is the name in the NLSDEFDIRMAP parameter in the uvconfig file.

Use the OPENSEQ pathname statement to open a UNIX pipe, file, or a file specified by a device that uses a map defined in the .uvnlsmap file in the directory holding pathname. If there is no .uvnlsmap file in the directory, the default mapname is the name in the NLSDEFSEQMAP parameter in the uvconfig file, or you can use the SET.SEQ.MAP command to assign a map.

File Buffering

Normally InfoSphere® DataStage® uses buffering for sequential input and output operations. Use the NOBUF statement after an OPENSEQ statement to turn off buffering and cause all writes to the file to be performed immediately. For more information about file buffering, see the NOBUF statement.

The USING Clause

You can optionally include the USING clause to control whether the opened file is included in the rotating file pool. The USING clause supplements OPENSEQ processing with a dynamic array whose structure emulates an &DEVICE& file record. Field 17 of the dynamic array controls inclusion in the rotating file pool with the following values:

  • Y removes the opened file.
  • N includes the opened file.

The ON ERROR Clause

The ON ERROR clause is optional in the OPENSEQ 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 OPENSEQ 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 LOCKED Clause

The LOCKED clause is optional, but recommended. Its syntax is the same as that of the ELSE clause. The LOCKED clause handles a condition caused by a conflicting lock (set by another user) that prevents the OPENSEQ statement from processing. The LOCKED clause is executed if one of the following conflicting locks exists:

  • Exclusive file lock
  • Intent file lock
  • Shared file lock
  • Update record lock
  • Shared record lock

If the OPENSEQ statement does not include a LOCKED clause, and a conflicting lock exists, the program pauses until the lock is released.

Use the STATUS function after an OPENSEQ statement to determine whether the file was successfully opened.

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.
-21
Null filename or file.
-3
Operating system access error that occurs when you do not have privileges 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.
-41
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.
-81
Invalid part file information.
-91
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.
-131
Index problem.
-14
Cannot open the NFS file.

1 A generic error that can occur for various reasons.

Examples

The following example reads RECORD1 from the file FILE.E, which is not hashed:

OPENSEQ 'FILE.E', 'RECORD1' TO FILE THEN
   PRINT "'FILE.E' OPENED FOR PROCESSING"
   END ELSE ABORT
READSEQ A FROM FILE THEN PRINT A ELSE STOP

The next example writes the record read from FILE.E to the file /usr/depta/file1:

OPENSEQ '/usr/depta/file1' TO OUTPUT THEN
   PRINT "usr/depta/file1 OPENED FOR PROCESSING"
END ELSE ABORT
WRITESEQ A ON OUTPUT ELSE PRINT "CANNOT WRITE TO 
OUTPUT"
   .
   .
   .
CLOSESEQ FILE
CLOSESEQ OUTPUT
END

This is the program output:

FILE.E OPENED FOR PROCESSING
HI THERE
   .
   .
   .
/usr/depta/file1 OPENED FOR PROCESSING

The next example includes the USING clause to remove an opened file from the rotating file pool:

DEVREC = "1"@FM
FOR I = 2 TO 16
   DEVREC = DEVREC:I:@FM
NEXT I
DEVREC=DEVREC:'Y'
*
OPENSEQ 'SEQTEST', 'TESTDATA' TO TESTFILE USING 
DEVREC 
THEN PRINT "OPENED 'TESTDATA' OK...."
ELSE PRINT "COULD NOT OPEN TESTDATA"
CLOSESEQ TESTFILE

This is the program output:

OPENED 'TESTDATA' OK
Parent topic: BASIC Statements and Functions