Utilities for Reading TeimOrbit Format Property Files

Given unit strings read from a property file, ACUNFN returns conversion factors from property file units to model and SI units. Generally, you proceed a call to ACUNFN by a call to ATRTOU to read the [UNITS] block from a property file.

You use the unit conversion factors that ACUNFN returns to convert data read from a property file to either model or SI units (Newtons, kilograms, meters, seconds, radian). For example, if you read a damping coefficient from a property file that has units of force*time/length and you need to convert that value to model units, then you might do the following:

damp_coeff = damp_coeff*CV2MDL(1)*CV2MDL(4)/CV2MDL(3)

Arguments

Argument:	Type*:	Storage:	Use* and Description:
UNITS ■UNITS(1): force ■UNITS (2): mass ■UNITS (3): length ■UNITS (4): time ■UNITS (5): angle	CA	12x5	R	Array of five 12-character strings read from the property file containing the unit names.
CV2MDL ■CV2MDL(1) Force conversion ■CV2MDL(2) Mass conversion ■CV2MDL(3) Length conversion ■CV2MDL(4) Time conversion ■CV2MDL(5) Angle conversion	DA	5	E	Conversion factor from property file units to model (dataset) units.
CV2SI ■CV2SI(1) Force conversion ■CV2SI(2) Mass conversion ■CV2SI(3) Length conversion ■CV2SI(4) Time conversion ■CV2SI(5) Angle conversion	DA	5	E	Conversion factor from property file units to SI units. SI units are Newtons, kilograms, meters, seconds, and radian.
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (for example, the subroutine sets the value of this argument).

ACUNFN_F2C

Calling Sequence

Subroutine ACUNFN_F2C ( FORCE, MASS, LENGTH, TIME, ANGLE, CV2MDL, CV2SI)

Description

Provides an entry point to ACUNFN from C-language routines.

Arguments

Argument:	Type*:	Storage:	Use* and Description:
FORCE	C	12	R	Force string from property file [UNITS] block.
MASS	C	12	R	Mass string from property file [UNITS] block.
LENGTH	C	12	R	Length string from property file [UNITS] block.
TIME	C	12	R	Time string from property file [UNITS] block.
ANGLE	C	12	R	Angle string from property file [UNITS] block.
CV2MDL ■CV2MDL(2) Mass conversion ■CV2MDL(3) Length conversion ■CV2MDL(4) Time conversion ■CV2MDL(5) Angle conversion	DA	5	E	Conversion factor from property file units to model (dataset) units.
CV2SI ■CV2SI(1) Force conversion ■CV2SI(2) Mass conversion ■CV2SI(3) Length conversion ■CV2SI(4) Time conversion ■CV2SI(5) Angle conversion	DA	5	E	Conversion factor from property file units to SI units. SI units are Newtons, kilograms, meters, seconds, and radian.
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

ACUNMP

Calling Sequence

Subroutine ACUNMP ( UN_IN, UN_OUT )

Description

Maps standard property file (Adams View) unit strings to Adams Solver unit strings.

Arguments

Argument:	Type:	Storage:	Use* and Description:
UN_IN ■UN_IN(1): force ■UN_IN(2): mass ■UN_IN(3): length ■UN_IN(4): time ■UN_IN(5): angle	CA	12x5	R	Array of five 12-character strings read from the property file containing the unit names.
UN_OUT	CA	2x5	E	Array of five two-character strings containing the Adams Solver unit string corresponding to the unit strings read from the property file.
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

ATRTOU

Calling Sequence

SubroutineATRTOU (ID, UNITS)

Description

Reads the [UNITS] block from a property file and returns a character array containing the unit strings for force, mass, length, time, and angle. Use ATRTOU with ACUNFNto obtain conversion factors from property file units to model units or SI units.

Before calling ATRTOU, you must call RTO_OPEN_FILE_F2C to open the property file for reading. If the [UNITS] block is not found in the file or there is a problem reading one of the unit strings, ARTOU writes a message to the message file and terminates Adams Solver execution.

Arguments

Argument:	Type*:	Storage:	Use* and Description:
ID	I	-	R	Identifier of the Adams dataset statement associated with the property file being read (for example, the ID of the tire GFORCE statement when reading a tire property file). Identifies the statement when an error occurs.
UNITS ■UNITS(1): force ■UNITS(2): mass ■UNITS(3): length ■UNITS(4): time ■UNITS(5): angle	CA	12x5	E	Array of five 12-character strings read from the tire property file containing the unit names.
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (for example, the subroutine sets the value of this argument).

RTO_CLOSE_FILE_F2C

Calling Sequence

Subroutine RTO_CLOSE_FILE_F2C (FileName, FileNameLen, Success)

Description

Closes a previously opened file.

Arguments

Argument:	Type*:	Storage:	Use* and description:
FileName	C	256	R	File name with full path
FileNameLen	I	-	R	Number of characters in the file name (not the length of the FileName array).
Success	I	-	E	■If the file was found and closed, success is returned as one (1). ■If the file was not found or could not be closed, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_OPEN_FILE_F2C

Calling Sequence

Subroutine RTO_OPEN_FILE_F2C (FileName, FileNameLen, Success)

Description

Opens a file for reading by the TeimOrbit utilities.

Note:

Before using any of the other RTO utilities, you must first open a file using this subroutine.

Arguments

Argument:	Type*:	Storage:	Use* and description:
FileName	C	256	R	File name with full path (for example, '/usr/people/smith/tire.tir')
FileNameLen	I	-	R	Number of characters in the file name (not the length of the FileName array).
Success	I	-	E	■If the file was found and opened, success is returned as one (1). ■If the file was not previously opened, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_READ_INTEGER_F2C

Calling Sequence

Subroutine RTO_READ_INTEGER_F2C (
BlockName, BlockNameLen,
AttributeName, AttribNameLen,
Value, Success )

Description

Reads an integer value assigned to an attribute in a block in the open file. For example, the call:

CALL RTO_READ_INTEGER_F2C( 'GEAR_RATIOS', 11,
+ 'N_GEARS', 7, Value, Success)

will read this from an open file:

[GEAR_RATIOS]
N_GEARS = 5

On return, the integer variable Value is 5 and Success is 1.

Arguments

Argument:	Type*:	Storage:	Use* and Description:
BlockName	C	256	R	Block name in file containing the desired subblock.
BlockNameLen	I	-	R	Number of characters in the block name.
Attribute Name	C	256	R	The name of the attribute sought in the file.
Attribute NameLen	I	-	R	Number of characters in the attribute name.
Value	I	-	E	On return, the string value of the attribute.
Success	I	-	E	■If the value is read, success is returned as one (1). ■If the read fails, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_READ_QUOTED_STRING_F2C

Calling Sequence

Subroutine

RTO_READ_QUOTED_STRING_F2C

( BlockName, BlockNameLen,
AttributeName, AttribNameLen,
Value, ValueLen, Success )

Description

Reads the string associated with an attribute in a block of a file. For example, the call:

CALL RTO_READ_QUOTED_STRING_F2C( 'MYBLOCK', 7, 'MYSTRING',
+ 8, Value, ValueLen, Success)

reads the data:

[MYBLOCK]
MYSTRING = 'heretofore'

On return:

■The character array Value holds ‘heretofore’

■The integer ValueLen is 10

■Success is 1

Arguments

Argument:	Type*:	Storage:	Use* and description:
BlockName	C	256	R	Block name in file containing the desired attribute.
BlockNameLen	I	-	R	Number of characters in the file name (not the length of the FileName array).
AttributeName	CI	-	R	Name of attribute sought in the file.
AttributeName Len	I	-	R	Number of characters in attribute name.
Value	C	256	E	On return the string value of the attribute.
ValueLen	I	-	E	Number of characters in value.
Success	I	-	E	■If a value is read, success is returned as one (1). ■If the read fails, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_READ_REAL_F2C

Calling Sequence

Subroutine RTO_READ_REAL_F2C (
BlockName, BlockNameLen,
AttributeName, AttribNameLen,
Value, Success)

Description

Reads a real value assigned to an attribute in a block in the open file. For example, the call:

CALL RTO_READ_INTEGER_F2C('GEAR_RATIOS', 11,
+ 'FINAL_DRIVE', 11, Value, Success)

reads this data from an open file:

[GEAR_RATIOS]
FINAL_DRIVE = 4.11

On return, the variable Value is 4.11 and Success is 1.

Arguments

Argument:	Type*:	Storage:	Use* and Description:
BlockName	C	256	R	Block name in file containing the desired subblock.
BlockNameLen	I	-	R	Number of characters in the block name.
Attribute Name	C	256	R	The name of the attribute sought in the file.
Attribute NameLen	I	-	R	Number of characters in the attribute name.
Value	D	-	E	On return, the value of the attribute.
Success	I	-	E	■If the value is read, success is returned as one (1). ■If the read fails, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_READ_SUBBLOCK_INTEGER_F2C

Calling Sequence

Subroutine RTO_READ_SUBBLOCK_INTEGER_F2C (
BlockName, BlockNameLen,
SubBlockName, SubBlockNameLen,
AttributeName, AttribNameLen,
Value, Success)

Description

Reads an integer value assigned to an attribute in a subblock of a block in the open file. For example, the call:

CALL RTO_READ_SUBBLOCK_INTEGER_F2C( 'TIRE_DATA', 9,
+ 'LATERAL_FORCE', 13, 'N_SLIP_ANGLES', 13,
+ Value, Success )

reads this data from the file:

[TIRE_DATA]
(LATERAL_FORCE)
N_SLIP_ANGLES = 6

On return, the integer variable Value is 6 and Success is 1.

Arguments

Argument:	Type*:	Storage:	Use* and Description:
BlockName	C	256	R	Block name in file containing the desired subblock.
BlockNameLen	I	-	R	Number of characters in the block name.
SubBlockName	C	256	R	Name of subblock in file containing the desired attribute.
SubBlockNameLen	I	-	R	Number of characters in the subblock name.
Attribute Name	C	256	R	The name of the attribute sought in the file.
Attribute NameLen	I	-	R	Number of characters in the attribute name.
Value	I	-	E	On return the value of the attribute.
Success	I	-	E	■If the value is read, success is returned as one (1). ■If the read fails, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_READ_SUBBLOCK_REAL_F2C

Calling Sequence

Subroutine

RTO_READ_SUBBLOCK_REAL_F2C (
BlockName, BlockNameLen, SubBlockName, SubBlockNameLen,
AttributeName, AttribNameLen,

Value, Success)

Description

Reads a real value assigned to an attribute in a subblock of a block in the open file. For example, the call:

CALL RTO_READ_SUBBLOCK_REAL_F2C( 'FORCES', 6, 'FY', 2,
+ 'DAMPING_COEFF', 13, Value, Success )

reads this data from an open file:

[FORCES]
(FY)
DAMPING_COEFF = 1.72

On return, the variable Value is 1.72 and Success is 1.

Arguments

Argument:	Type*:	Storage:	Use* and Description:
BlockName	C	256	R	Block name in file containing the desired subblock.
BlockNameLen	I	-	R	Number of characters in the block name.
SubBlockName	C	256	R	Name of subblock in file containing the desired attribute.
SubBlockNameLen	I	-	R	Number of characters in the subblock name.
Attribute Name	C	256	R	The name of the attribute sought in the file.
Attribute NameLen	I	-	R	Number of characters in the attribute name.
Value	D	-	E	On return the value of the attribute.
Success	I	-	E	■If the value is read, success is returned as one (1). ■If the read fails, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_READ_SUBBLOCK_STRING_F2C

Calling Sequence

Subroutine RTO_READ_SUBBLOCK_STRING_F2C (
BlockName, BlockNameLen,
SubBlockName, SubBlockNameLen,
AttributeName, AttribNameLen,
Value, ValueLen, Success )

Description

Reads a string assigned to an attribute in a subblock of a block in the open file. For example, the call:

CALL RTO_READ_SUBBLOCK_STRING_F2C( 'FORCES', 6, 'FY',
+ 2, 'DAMPING', 7, Value, ValueLen, Success )

reads the data:

[FORCES]
(FY)
DAMPING = 'on'

On return:

■Character array Value holds ‘on’

■The integer ValueLen is 2

■Success is 1

Arguments

Argument:	Type*:	Storage:	Use* and Description:
BlockName	C	256	R	Block name in file containing the desired subblock.
BlockNameLen	I	-	R	Number of characters in the block name.
SubBlockName	C	256	R	Name of subblock in file containing the desired attribute
SubBlockNameLen	I	-	R	Number of characters in the subblock name.
Attribute Name	C	256	R	The name of the attribute sought in the file.
Attribute NameLen	I	-	R	Number of characters in the attribute name.
Value	C	256	E	On return the string value of attribute.
ValueLen	I	-	E	Number of characters in value.
Success	I	-	E	■If the value is read, success is returned as one (1). ■If the read fails, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_READ_TABLE_LINE_F2C

Calling Sequence

Subroutine RTO_READ_TABLE_LINE_F2C

(Value, ValueLen, Success)

Description

Reads a single line from a table. Use RTO_READ_TABLE_LINE_F2C after first locating the start of table using either RTO_START_TABLE_READ_F2C or RTO_START_SUBBLOCK_TABLE_READ_F2C. Typically, you use RTO_READ_TABLE_LINE_F2C in a while loop to read an entire table. For example, to read this table:

[MYBLOCK]

{ X Y }

0.0 0.24

0.1 0.48

0.3 0.96

Use code, such as the following:

c --- Locate the start of the table ---

CALL RTO_START_TABLE_READ_F2C( 'MYBLOCK', 7,

+ Format, FormatLen, Success )

IF ( Success .eq. 0 ) THEN

c --- Table Not Found ---

ELSE

10 CONTINUE

CALL RTO_READ_TABLE_LINE_F2C( Value, ValueLen, Success )

IF ( Success .eq. 0 ) then

c --- End of table found ---

GOTO 20

ELSE

c --- Parse string in Value To retrieve values, then go

c get another line of the table.

c The first time through this loop Value holds

c " 0.0 0.24/n"

c The third time through this loop Value holds

c " 0.3 0.96/n"

c ---

GOTO 10

ENDIF

20 CONTINUE

Arguments

Argument:	Type*:	Storage:	Use* and Description:
Value	C	256	E	On return the nth line of a table.
ValueLen	I	-	R	Number of characters in value.
Success	I	-	E	■If the value is read from the table, success is returned as one (1). ■If the end of the table is found, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_START_SUBBLOCK_TABLE_READ_F2C

Calling Sequence

Subroutine RTO_START_SUBBLOCK_TABLE_READ_F2C (
BlockName, BlockNameLen, SubBlockName, SubBlockNameLen,
Format, FormatLen, Success )

Description

Locates the start of a table in a subblock of a block in a file before calling RTO_READ_TABLE_LINE_F2C. There can be only one table per subblock. The start of a table is denoted by braces {" and "}. For example, the call:

CALL RTO_START_SUBBLOCK_TABLE_READ_F2C

( 'MYBLOCK', 7,
+ 'MYSUBBLOCK', Format, FormatLen, Success)

Searches for this data in the open file:

[MYBLOCK]
(MYSUBBLOCK)
  { S FX FY }
   0.0 1.15 -2.13
   0.1 2.15 -2.13
   0.2 1.48 -2.13

On return:

■Format contains the string, “ _S_FX_FY”

■FormatLen contains the integer 9

■Success contains the integer 1

Arguments

Argument:	Type*:	Storage:	Use* and Description:
BlockName	C	256	R	Block name in file containing the desired subblock.
BlockNameLen	I	-	R	Number of characters in the block name.
SubBlockName	C	256	R	Name of subblock in file containing the desired attribute.
SubBlockNameLen	I	-	R	Number of characters in the subblock name.
Format	C	256	E	The string containing the table column headings.
FormatLen	I	-	E	The number of characters in the Format string.
Success	I	-	E	■If the value is read, success is returned as one (1). ■If the read fails, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).

RTO_START_TABLE_READ_F2C

Calling Sequence

Subroutine RTO_START_TABLE_READ_F2C (
BlockName, BlockNameLen, Format, FormatLen, Success)

Description

Locates the start of table in a block in a file before calling RTO_READ_TABLE_LINE_F2C. There can be only one table per block. The start of a table is denoted by braces {" and "}. For example, the call:

CALL RTO_START_TABLE_READ_F2C( 'MYBLOCK', 7, Format,
+ FormatLen, Success)

Searches for this data in the open file:

[MYBLOCK]
{ X Y }
0.0 0.24
0.1 0.48
0.3 0.96

On return:

■Format contains the string, " XY"

■FormatLen contains the integer 6

■Success contains the integer 1

Arguments

Argument:	Type*:	Storage:	Use* and Description:
BlockName	C	256	R	Block name in file containing the desired subblock.
BlockNameLen	I	-	R	Number of characters in the block name.
Format	C	256	E	The string containing the table column headings.
FormatLen	I	-	E	The number of characters in the Format string.
Success	I	-	E	■If the value is read, success is returned as one (1). ■If the read fails, success is returned as zero (0).
*Key: Type: A = array; C = character; D = double precision; I = integer (for example, DA indicates double-precision array). Use: R = referenced, but not set; E = evaluated (the subroutine sets the value of this argument).