HP Fortran for OpenVMS
Language Reference Manual

9.4.160 TRANSPOSE (MATRIX)

Description:	Transposes an array of rank two.
Class:	Transformational function; Generic
Arguments:	MATRIX must be a rank-two array (of any data type).
Results:	The result is a rank-two array with the same type and kind parameters as MATRIX. Its shape is (n, m), where (m, n) is the shape of MATRIX. For example, if the shape of MATRIX is (4,6), the shape of the result is (6,4). Element (i, j) of the result has the value MATRIX (j, i), where i is in the range 1 to n, and j is in the range 1 to m.

Examples

B is the array <left[ symbol><matrix symbol> 2&3&4<cr symbol> 5&6&7<cr symbol> 8&9&1<cr symbol> <right] symbol> .

TRANSPOSE (B) has the value <left[ symbol><matrix symbol> 2&5&8<cr symbol> 3&6&9<cr symbol> 4&7&1<cr symbol> <right] symbol> .

9.4.161 TRIM (STRING)

Description:	Returns the argument with trailing blanks removed.
Class:	Transformational function; Generic
Arguments:	STRING must be a scalar of type character.
Results:	The result is of type character with the same kind parameter as STRING. Its length is the length of STRING minus the number of trailing blanks in STRING. The value of the result is the same as STRING, except any trailing blanks are removed. If STRING contains only blank characters, the result has zero length.

Examples

TRIM ( ' --NAME---- ' ) has the value ' --NAME ' .

TRIM ( ' --C--D----- ' ) has the value ' --C--D ' .

9.4.162 UBOUND (ARRAY [,DIM] [,KIND])

Description:	Returns the upper bounds for all dimensions of an array, or the upper bound for a specified dimension.
Class:	Inquiry function; Generic
Arguments:	ARRAY	Must be an array (of any data type). It must not be an allocatable array that is not allocated, or a disassociated pointer. It can be an assumed-size array if DIM is present with a value less than the rank of ARRAY.
	DIM (opt)	Must be a scalar integer with a value in the range 1 to n, where n is the rank of ARRAY.
	KIND (opt)	Must be a scalar integer initialization expression.
Results:	The result type is integer. If KIND is present, the kind parameter of the result is that specified by KIND; otherwise, the kind parameter of the result is that of default integer. If the processor cannot represent the result value in the kind of the result, the result is undefined. If DIM is present, the result is a scalar. Otherwise, the result is a rank-one array with one element for each dimension of ARRAY. Each element in the result corresponds to a dimension of ARRAY. If ARRAY is an array section or an array expression that is not a whole array or array structure component, UBOUND (ARRAY, DIM) has a value equal to the number of elements in the given dimension. If ARRAY is a whole array or array structure component, UBOUND (ARRAY, DIM) has a value equal to the upper bound for subscript DIM of ARRAY (if DIM is nonzero). If DIM has size zero, the corresponding element of the result has the value zero. The setting of compiler options that specify integer size can affect the result of this function.

Examples

Consider the following:

REAL ARRAY_A (1:3, 5:8) REAL ARRAY_B (2:8, -3:20)

UBOUND (ARRAY_A) is (3, 8). UBOUND (ARRAY_A, DIM=2) is 8.

UBOUND (ARRAY_B) is (8, 20). UBOUND (ARRAY_B (5:8, :)) is (4,24) because the number of elements is significant for array section arguments.

9.4.163 UNPACK (VECTOR, MASK, FIELD)

Description:	Takes elements from a rank-one array and unpacks them into another (possibly larger) array under the control of a mask.
Class:	Transformational function; Generic
Arguments:	VECTOR	Must be a rank-one array (of any data type). Its size must be at least t, where t is the number of true elements in MASK.
	MASK	Must be a logical array. It determines where elements of VECTOR are placed when they are unpacked.
	FIELD	Must be of the same type and type parameters as VECTOR and conformable with MASK. Elements in FIELD are inserted into the result array when the corresponding MASK element has the value false.
Results:	The result is an array with the same shape as MASK, and the same type and type parameters as VECTOR. Elements in the result array are filled in array element order. If element i of MASK is true, the corresponding element of the result is filled by the next element in VECTOR. Otherwise, it is filled by FIELD (if FIELD is scalar) or the ith element of FIELD (if FIELD is an array).

Examples

N is the array <left[ symbol><matrix symbol> 0&0&1<cr symbol> 1&0&1<cr symbol> 1&0&0<cr symbol> <right] symbol> , P is the array (2, 3, 4, 5), and Q is the array <left[ symbol><matrix symbol> T&F&F<cr symbol> F&T&F<cr symbol> T&T&F<cr symbol> <right] symbol> .

UNPACK (P, MASK=Q, FIELD=N) produces the result <left[ symbol><matrix symbol> 2&0&1<cr symbol> 1&4&1<cr symbol> 3&5&0<cr symbol> <right] symbol> .

UNPACK (P, MASK=Q, FIELD=1) produces the result <left[ symbol><matrix symbol> 2&1&1<cr symbol> 1&4&1<cr symbol> 3&5&1<cr symbol> <right] symbol> .

9.4.164 VERIFY (STRING, SET [,BACK] [,KIND])

Description:	Verifies that a set of characters contains all the characters in a string by identifying the first character in the string that is not in the set.
Class:	Elemental function; Generic
Arguments:	STRING	Must be of type character.
	SET	Must be of type character with the same kind parameter as STRING.
	BACK (opt)	Must be of type logical.
	KIND (opt)	Must be a scalar integer initialization expression.
Results:	The result is of type integer. If KIND is present, the kind parameter of the result is that specified by KIND; otherwise, the kind parameter of the result is that of default integer. If the processor cannot represent the result value in the kind of the result, the result is undefined. If BACK is omitted (or is present with the value false) and STRING has at least one character that is not in SET, the value of the result is the position of the leftmost character of STRING that is not in SET. If BACK is present with the value true and STRING has at least one character that is not in SET, the value of the result is the position of the rightmost character of STRING that is not in SET. If each character of STRING is in SET or the length of STRING is zero, the value of the result is zero.

Examples

VERIFY ( ' CDDDC ' , ' C ' ) has the value 2.

VERIFY ( ' CDDDC ' , ' C ' , BACK=.TRUE.) has the value 4.

VERIFY ( ' CDDDC ' , ' CD ' ) has the value zero.

9.4.165 ZEXT (X [,KIND])

Description:	Extends the argument with zeros. This function is used primarily for bit-oriented operations.
Class:	Elemental function; Generic
Arguments:	X	Must be of type logical or integer.
	KIND (opt)	Must be a scalar integer initialization expression.
Results:	The result is of type integer. If KIND is present, the kind parameter of the result is that specified by KIND; otherwise, the kind parameter of the result is that of default integer. If the processor cannot represent the result value in the kind of the result, the result is undefined. The result value is X extended with zeros and treated as an unsigned value.
	The storage requirements for integer constants are never less than two bytes. Integer constants within the range of constants that can be represented by a single byte still require two bytes of storage. The setting of compiler options specifying integer size can affect ZEXT.

Specific Name	Argument Type	Result Type
IZEXT	LOGICAL(1)	INTEGER(2)
	LOGICAL(2)	INTEGER(2)
	INTEGER(1)	INTEGER(2)
	INTEGER(2)	INTEGER(2)
JZEXT	LOGICAL(1)	INTEGER(4)
	LOGICAL(2)	INTEGER(4)
	LOGICAL(4)	INTEGER(4)
	INTEGER(1)	INTEGER(4)
	INTEGER(2)	INTEGER(4)
	INTEGER(4)	INTEGER(4)
KZEXT	LOGICAL(1)	INTEGER(8)
	LOGICAL(2)	INTEGER(8)
	LOGICAL(4)	INTEGER(8)
	LOGICAL(8)	INTEGER(8)
	INTEGER(1)	INTEGER(8)
	INTEGER(2)	INTEGER(8)
	INTEGER(4)	INTEGER(8)
	INTEGER(8)	INTEGER(8)

Examples

Consider the following example:

INTEGER(2) W_VAR /'FFFF'X/ INTEGER(4) L_VAR L_VAR = ZEXT(W_VAR)

This example stores an INTEGER(2) quantity in the low-order 16 bits of an INTEGER(4) quantity, with the resulting value of L_VAR being ' 0000FFFF ' X. If the ZEXT function had not been used, the resulting value would have been ' FFFFFFFF ' X, because W_VAR would have been converted to the left-hand operand's data type by sign extension.

Chapter 10
Data Transfer I/O Statements

This chapter describes:

File connection, file inquiry, and file positioning I/O statements are discussed in Chapter 12.

10.1 Overview of Records and Files

A record is a sequence of values or a sequence of characters. There are three kinds of Fortran records:

Formatted
A record containing formatted data that requires translation from internal to external form. Formatted I/O statements have explicit format specifiers (which can specify list-directed formatting) or namelist specifiers (for namelist formatting). Only formatted I/O statements can read formatted data.
Unformatted
A record containing unformatted data that is not translated from internal form. An unformatted record can also contain no data. The internal representation of unformatted data is processor-dependent. Only unformatted I/O statements can read unformatted data.
Endfile
The last record of a file. An endfile record can be explicitly written to a sequential file by an ENDFILE statement (see Section 12.4 for details).

A file is a sequence of records. There are two types of Fortran files, as follows:

External
A file that exists in a medium (such as computer disks or terminals) external to the executable program.
Records in an external file must be either all formatted or all unformatted. There are three ways to access records in external files: sequential, keyed access, and direct access.
In sequential access, records are processed in the order in which they appear in the file. In direct access, records are selected by record number, so they can be processed in any order. In keyed access, records are processed by key-field value.
Internal
Memory (internal storage) that behaves like a file. This type of file provides a way to transfer and convert data in memory from one format to another. The contents of these files are stored as scalar character variables.

For More Information:

On formatted and unformatted data transfers and external file access methods, see the HP Fortran for OpenVMS User Manual.

10.2 Components of Data Transfer Statements

Data transfer statements take one of the following forms:

io-keyword (io-control-list) [io-list] io-keyword format [,io-list]

io-keyword
Is one of the following: ACCEPT, PRINT (or TYPE), READ, REWRITE, or WRITE.
io-control-list
Is one or more of the following input/output (I/O) control specifiers:

[UNIT=]io-unit ADVANCE ERR KEYID

[FMT=]format END IOSTAT REC

[NML=]group EOR KEY[con] SIZE

io-list
Is an I/O list, which can contain variables (except for assumed-size arrays) or implied-do lists. Output statements can contain constants or expressions.
format
Is the nonkeyword form of a control-list format specifier (no FMT=).

If a format specifier ([FMT=]format) or namelist specifier ([NML=]group) is present, the data transfer statement is called a formatted I/O statement; otherwise, it is an unformatted I/O statement.

If a record specifier (REC=) is present, the data transfer statement is a direct-access I/O statement; otherwise, it is a sequential-access I/O statement.

If an error, end-of-record, or end-of-file condition occurs during data transfer, file positioning and execution are affected, and certain control-list specifiers (if present) become defined. (For more information, see Section 10.2.1.8.)

Section 10.2.1 describes the I/O control list and Section 10.2.2 describes I/O lists.

10.2.1 I/O Control List

The I/O control list specifies one or more of the following:

The I/O unit to act upon ([UNIT=]io-unit)
This specifier must be present; the rest are optional.
The format (explicit or list-directed) to use for data editing; if explicit, the keyword form must appear ([FMT=]format)
The namelist group name to act upon ([NML=]group)
The number of a record to access (REC)
The name of a variable that contains the completion status of an I/O operation (IOSTAT)
The label of the statement that receives control if an error (ERR), end-of-file (END), or end-of-record (EOR) condition occurs
The key field (KEY[con]) and key of reference (KEYID) to access a keyed-access record
Whether you want to use advancing or nonadvancing I/O (ADVANCE)
The number of characters read from a record (SIZE) by a nonadvancing READ statement

No control specifier can appear more than once, and the list must not contain both a format specifier and namelist group name specifier.

Control specifiers can take any of the following forms:

Keyword form
When the keyword form (for example, UNIT=io-unit) is used for all control-list specifiers in an I/O statement, the specifiers can appear in any order.
Nonkeyword form
When the nonkeyword form (for example, io-unit) is used for all control-list specifiers in an I/O statement, the io-unit specifier must be the first item in the control list. If a format specifier or namelist group name specifier is used, it must immediately follow the io-unit specifier.
Mixed form
When a mix of keyword and nonkeyword forms is used for control-list specifiers in an I/O statement, the nonkeyword values must appear first. Once a keyword form of a specifier is used, all specifiers to the right must also be keyword forms.

The following sections describe the control-list specifiers in detail.

10.2.1.1 Unit Specifier

The unit specifier identifies the I/O unit to be accessed. It takes the following form:

[UNIT=]io-unit

io-unit
For external files, it identifies a logical unit and is one of the following:

A scalar integer expression that refers to a specific file, I/O device, or pipe. If necessary, the value is converted to integer data type before use. The integer is in the range 0 through 2**31--1.
Units 5 and 6 are associated with preconnected units.
An asterisk (*). This is the default (or implicit) external unit, which is preconnected for formatted sequential access.

For internal files, io-unit identifies a scalar or array character variable that is an internal file. An internal file is designated internal storage space (a variable buffer) that is used with formatted (including list-directed) sequential READ and WRITE statements.

The io-unit must be specified in a control list. If the keyword UNIT is omitted, the io-unit must be first in the control list.

A unit number is assigned either explicitly through an OPEN statement or implicitly by the system. If a READ statement implicitly opens a file, the file's status is STATUS= ' OLD ' . If a WRITE statement implicitly opens a file, the file's status is STATUS= ' NEW ' .

If the internal file is a scalar character variable, the file has only one record; its length is equal to that of the variable.

If the internal file is an array character variable, the file has a record for each element in the array; each record's length is equal to one array element.

An internal file can be read only if the variable has been defined and a value assigned to each record in the file. If the variable representing the internal file is a pointer, it must be associated; if the variable is an allocatable array, it must be currently allocated.

Before data transfer, an internal file is always positioned at the beginning of the first character of the first record.

For More Information:

On the OPEN statement, see Section 12.6 for details.
On implicit logical assignments, see the HP Fortran for OpenVMS User Manual.
On preconnected units, see the HP Fortran for OpenVMS User Manual.
On using internal files, see the HP Fortran for OpenVMS User Manual.

Contents

Index

[UNIT=]io-unit	ADVANCE	ERR	KEYID
[FMT=]format	END	IOSTAT	REC
[NML=]group	EOR	KEY[con]	SIZE

HP Fortran for OpenVMSLanguage Reference Manual

9.4.160 TRANSPOSE (MATRIX)

Chapter 10Data Transfer I/O Statements

io-keyword

io-control-list

io-list

format

io-unit

HP Fortran for OpenVMS
Language Reference Manual

Chapter 10
Data Transfer I/O Statements