MATWRITE statements

Syntax

MATWRITE[U] array ON | TO [file.variable,] record.ID[ON ERROR statements] [LOCKED statements] 
[THEN statements] [ELSE statements]

Description

Use the MATWRITE statement to write data from the elements of a dimensioned array to a record in an InfoSphere® DataStage® file. The elements of array replace any data stored in the record. MATWRITE strips any trailing empty fields from the record.

file.variable specifies an open file. If file.variable is not specified, the default file is assumed (for more information on default files, see the OPEN statement). If the file is neither accessible nor open, the program terminates with a run-time message, unless ELSE statements are specified.

If the file is an SQL table, the effective user of the program must have SQL INSERT and UPDATE privileges to read records in the file. For information about the effective user of a program, see the AUTHORIZATION statement.

If the OPENCHK configurable parameter is set to TRUE, or if the file is opened with the OPENCHECK statement, all SQL integrity constraints are checked for every MATWRITE to an SQL table. If an integrity check fails, the MATWRITE statement uses the ELSE clause. Use the ICHECK function to determine what specific integrity constraint caused the failure.

The system searches the file for the record specified by record.ID. If the record is not found, MATWRITE creates a new record.

If NLS is enabled, MATWRITE and other BASIC statements that perform I/O operations always map internal data to the external character set using the appropriate map for the output file. For details, see the WRITE statements statement.

The ON ERROR Clause

The ON ERROR clause is optional in the MATWRITE statement. The ON ERROR clause lets you specify an alternative for program termination when a fatal error is encountered while the MATWRITE 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.

The LOCKED clause handles a condition caused by a conflicting lock (set by another user) that prevents the MATWRITE 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 MATWRITE statement does not include a LOCKED clause, and a conflicting lock exists, the program pauses until the lock is released.

When updating a file, MATWRITE releases the update record lock set with a MATREADU statement. To maintain the update record lock set with the MATREADU statement, use MATWRITEU instead of MATWRITE.

The new values are written to the record, and the THEN clauses are executed. If no THEN statements are specified, execution continues with the statement following the MATWRITE statement.

If either file.variable or record.ID evaluates to the null value, the MATWRITE statement fails and the program terminates with a run-time error message. Null elements of array are written to record.ID as the stored representation of the null value, CHAR(128).

The MATWRITEU Statement

Use the MATWRITEU statement to update a record without releasing the update record lock set by a previous MATREADU statement (see the MATREAD statements statement). To release the update record lock set by a MATREADU statement and maintained by a MATWRITEU statement, you must use a RELEASE or MATWRITE statement. If you do not explicitly release the lock, the record remains locked until the program executes the STOP statement. When more than one program or user could modify the same record, use a MATREADU statement to lock the record before doing the MATWRITE or MATWRITEU.

IDEAL and INFORMATION Flavors

In IDEAL and INFORMATION flavor accounts, if the zero element of the array has been assigned a value by a MATREAD or MATREADU statement, the zero element value is written to the record as the n+1 field, where n is the number of elements dimensioned in the array. If the zero element is assigned an empty string, only the assigned elements of the array are written to the record; trailing empty fields are ignored. The new record is written to the file (replacing any existing record) without regard for the size of the array.

It is generally good practice to use the MATWRITE statement with arrays that have been loaded with either a MATREAD or a MATREADU statement.

After executing a MATWRITE statement, you can use the STATUS function to determine the result of the operation as follows (see the STATUS function for more information):

0
The record was locked before the MATWRITE operation.
-2
The record was unlocked before the MATWRITE operation.
-3
The record failed an SQL integrity check.

Example

DIM ARRAY(5)
OPEN 'EX.BASIC' TO EX.BASIC ELSE STOP 'CANNOT OPEN'
MATREADU ARRAY FROM EX.BASIC, 'ABS' ELSE STOP
ARRAY(1)='Y = 100'
MATWRITE ARRAY TO EX.BASIC, 'ABS'
PRINT 'STATUS()= ',STATUS()

This is the program output:

STATUS()=     0
Parent topic: BASIC Statements and Functions