MATREAD statements

Syntax

MATREAD array FROM [file.variable,] record.ID [ON ERROR 
statements]
{THEN statements [ELSE statements] | ELSE statements}
{ MATREADL | MATREADU } array FROM [file.variable,] 
record.ID 
[ON ERROR statements] [LOCKED statements] 
{THEN statements [ELSE statements] | ELSE statements}

Description

Use the MATREAD statement to assign the contents of the fields of a record from an InfoSphere® DataStage® file to consecutive elements of array. The first field of the record becomes the first element of array, the second field of the record becomes the second element of array, and so on. The array must be named and dimensioned in a DIMENSION statement or COMMON statement before it is used in this statement.

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

If record.ID exists, array is set to the contents of the record, and the THEN statements are executed; any ELSE statements are ignored. If no THEN statements are specified, program execution continues with the next sequential statement. If record.ID does not exist, the elements of array are not changed, and the ELSE statements are executed; any THEN statements are ignored.

If either file.variable or record.ID evaluates to the null value, the MATREAD statement fails and the program terminates with a run-time error. If any field in the record is the null value, null becomes an element in array. If a value or a subvalue in a multi-valued field is the null value, it is read into the field as the stored representation of null (CHAR(128)).

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

A MATREAD statement does not set an update record lock on the specified record. That is, the record remains available for update to other users. To prevent other users from updating the record until it is released, use a MATREADL or MATREADU statement.

If the number of elements in array is greater than the number of fields in the record, the extra elements in array are assigned empty string values. If the number of fields in the record is greater than the number of elements in the array, the extra values are stored in the zero element of array for IDEAL or INFORMATION flavor accounts, or in the last element of array for PICK, IN2, or REALITY flavor accounts. The zero element of an array can be accessed with a 0 subscript as follows:

MATRIX (0)

or:

MATRIX (0, 0)

Use the INMAT function after a MATREAD statement to determine the number of elements of the array that were actually used. If the number of fields in the record is greater than the number of elements in the array, the value of the INMAT function is set to 0.

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

The ON ERROR Clause

The ON ERROR clause is optional in MATREAD statements. 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 during processing of the MATREAD statement.

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 MATREAD statement from processing. The LOCKED clause is executed if one of the following conflicting locks exists:

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

If a LOCKED clause is used, the value returned by the STATUS function is the terminal number of the user who owns the conflicting lock.

Releasing Locks

A shared record lock can be released with a CLOSE statement, RELEASE statement, or STOP statement. An update record lock can be released with a CLOSE, DELETE, MATWRITE statements, RELEASE, STOP, , or statement.

Locks acquired or promoted within a transaction are not released when the previous statements are processed.

MATREADL and MATREADU Statements

Use the MATREADL syntax to acquire a shared record lock and then perform a MATREAD. This lets other programs read the record with no lock or a shared record lock.

Use the MATREADU syntax to acquire an update record lock and then perform a MATREAD. The update record lock prevents other users from updating the record until the user who set it releases it.

An update record lock can be acquired when no shared record lock exists, or promoted from a shared record lock owned by you if no other shared record locks exist.

Example

DIM ARRAY(10)
OPEN 'SUN.MEMBER' TO SUN.MEMBER ELSE STOP
MATREAD ARRAY FROM SUN.MEMBER, 6100 ELSE STOP
*
FOR X=1 TO 10
PRINT "ARRAY(":X:")",ARRAY(X)
NEXT X
*
PRINT
*
DIM TEST(4)
OPEN '','SUN.SPORT' ELSE STOP 'CANNOT OPEN SUN.SPORT'
MATREAD TEST FROM 851000 ELSE STOP
*
FOR X=0 TO 4
PRINT "TEST(":X:")",TEST(X)
NEXT X

This is the program output:

ARRAY(1) MASTERS
ARRAY(2) BOB
ARRAY(3) 55 WESTWOOD ROAD
ARRAY(4) URBANA
ARRAY(5) IL
ARRAY(6) 45699
ARRAY(7) 1980
ARRAY(8) SAILING
ARRAY(9)
ARRAY(10)     II
TEST(0) 6258
TEST(1) 6100
TEST(2) HARTWELL
TEST(3) SURFING
TEST(4) 4