Intrinsic Functions

PCL and Customization > Basic Functions > Intrinsic Functions

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">

Intrinsic Functions

PCL has an extensive library of intrinsic functions accessible at any time. Each function name is prefixed with a several letter mnemonic which specifies the category.

Most--but not all--PCL functions return a value. In the descriptions below, the definition of the return value is shown under the output parameters by using the name of the function as the variable name to be returned.

PCL intrinsic functions are more flexible than normal PCL functions when it comes to passing simple integers and reals. If an intrinsic function calls for a non-array input only integer or real value, pass either an integer or a real for that argument and PCL will convert automatically to the needed type.

Many PCL intrinsic functions are specific to the Patran environment and allow sophisticated control of the database and user interface. These PCL functions are documented elsewhere. The PCL functions documented here represent a core set of routines to perform many general operations such as math, string manipulation, and file input/output. The following documentation breaks down the intrinsic functions by categories.

Math Functions

PCL contains a large number of intrinsic mathematical functions. Since the math functions are used so often, the prefix MTH_ is optional when referring to the Math Functions (unless otherwise specified in the documentation).


mth_sind	( angle )


Description:
Return trigonometric sine value of the argument specified in degrees.
Input:
REAL	angle	The angle in degrees for which to compute the sine
Output:
REAL	<Return Value>	The sine value.
Error Conditions:
None.


mth_asind	( value )


Description:
Return angle in degrees which corresponds to the trigonometric sine contained in the argument.
Input:
REAL	value	The sine value for which to find the angle.
Output:
REAL	<Return Value>	The angle in degrees for the sine.
Error Conditions:
None.


mth_cosd	( angle )


Description:
Return trigonometric cosine value of the argument specified in degrees.
Input:
REAL	angle	The angle in degrees for which to compute the cosine.
Output:
REAL	<Return Value>	The cosine value.
Error Conditions:
None.


mth_acosd	( value )


Description:
Return angle in degrees which corresponds to the trigonometric cosine contained in the argument.
Input:
REAL	value	The cosine value for which to find the angle.
Output:
REAL	<Return Value>	The angle in degrees for the cosine.
Error Conditions:
None.


mth_tand	( angle )


Description:
Return trigonometric tangent value of the argument specified in degrees.
Input:
REAL	angle	The angle in degrees for which to compute the tangent.
Output:
REAL	<Return Value>	The tangent value.
Error Conditions:
None.


mth_atand	( value )


Description:
Return angle in degrees which corresponds to the trigonometric tangent contained in the argument.
Input:
REAL	value	The tangent value for which to find the angle.
Output:
REAL	<Return Value>	The angle in degrees for the tangent.
Error Conditions:
None.


mth_atan2d	( y, x )


Description:
Return angle in degrees which corresponds to the trigonometric tangent represented by the specified x and y components.
Input:
REAL	y	The y component of the tangent.
REAL	x	The x component of the tangent.
Output:
REAL	<Return Value>	The angle in degrees for the tangent.
Error Conditions:
None.


mth_sinr	( angle )


Description:
Return trigonometric sine value of the argument specified in radians.
Input:
REAL	angle	The angle in radians for which to compute the sine.
Output:
REAL	<Return Value>	The sine value.
Error Conditions:
None.


mth_asinr	( value )


Description:
Return angle in radians which corresponds to the trigonometric sine contained in the argument.
Input:
REAL	value	The sine value for which to find the angle.
Output:
REAL	<Return Value>	The angle in radians for the sine.
Error Conditions:
None.


mth_cosr	( angle )


Description:
Return trigonometric cosine value of the argument specified in radians.
Input:
REAL	angle	The angle in radians for which to compute the cosine.
Output:
REAL	<Return Value>	The cosine value.
Error Conditions:
None.


mth_acosr	( value )


Description:
Return angle in radians which corresponds to the trigonometric cosine contained in the argument.
Input:
REAL	value	The cosine value for which to find the angle.
Output:
REAL	<Return Value>	The angle in radians for the cosine.
Error Conditions:
None.


mth_tanr	( angle )


Description:
Return trigonometric tangent value of the argument specified in radians.
Input:
REAL	angle	The angle in radians for which to compute the tangent.
Output:
REAL	<Return Value>	The tangent value.
Error Conditions:
None.


mth_atanr	( value )


Description:
Return angle in radians which corresponds to the trigonometric tangent contained in the argument.
Input:
REAL	value	The tangent value for which to find the angle.
Output:
REAL	<Return Value>	The angle in radians for the tangent.
Error Conditions:
None.


mth_atan2r	( y, x )


Description:
Return angle in degrees which corresponds to the trigonometric tangent represented by the specified x and y components.
Input:
REAL	y	The y component of the tangent.
REAL	x	The x component of the tangent.
Output:
REAL	<Return Value>	The angle in radians for the tangent.
Error Conditions:
None.


mth_sqrt	( value )


Description:
Return square root of the argument.
Input:
REAL	value	The value for which to obtain the square root.
Output:
REAL	<Return Value>	The square root.
Error Conditions:
None.


mth_ln	( value )


Description:
Return natural logarithm of the argument.
Input:
REAL	value	The value for which to obtain the natural logarithm.
Output:
REAL	<Return Value>	The natural logarithm.
Error Conditions:
None.


mth_log	( value )


Description:
Return common logarithm of the argument.
Input:
REAL	value	The value for which to obtain the common logarithm.
Output:
REAL	<Return Value>	The common logarithm.
Error Conditions:
None.


mth_exp	( value )


Description:
Return power function of natural logarithm base, e to the x power.
Input:
REAL	value	The raising power
Output:
REAL	<Return Value>	The result of the power of the input argument.
Error Conditions:
None.


mth_abs	( value )


Description:
Return the absolute value of the input argument.
Input:
NUMERIC	value	The value to get the absolute value of, integer or real.
Output:
NUMERIC	<Return Value>	The absolute value of the input argument. The datatype will match that of the input argument.
Error Conditions:
None.


mth_sign	( value )


Description:
Return a sign, -1, 0, or 1 for the input argument.
Input:
REAL	value	The value of which to get the sign.
Output:
INTEGER	<Return Value>	The sign value of the input argument, -1 for a negative argument, 0 for zero, and 1 for a positive argument.
Error Conditions:
None.


mth_nint	( value )


Description:
Return the nearest integer value for the input argument.
Input:
REAL	value	The value for which to obtain the nearest integer.
Output:
INTEGER	<Return Value>	The nearest integer value, rounding off the input argument.
Error Conditions:
None.


mth_max	( val1, val2, ... )


Description:
Return the largest value of a set of input values.
Input:
NUMERIC	valnnn	Input values to check, INTEGER or REAL. There may be one or more input values specified.
Output:
NUMERIC	<Return Value>	The largest value of the input arguments. If all input arguments are INTEGER, then this result is also INTEGER. Otherwise, this result is REAL.
Error Conditions:
None.


mth_min	( val1, val2, ... )


Description:
Return the smallest value of a set of input values.
Input:
NUMERIC	valnnn	Input values to check, INTEGER or REAL. There may be one or more input values specified.
Output:
NUMERIC	<Return Value>	The smallest value of the input arguments. If all input arguments are INTEGER, then this result is also INTEGER. Otherwise, this result is REAL.
Error Conditions:
None.


mth_mod	( value, divisor )


Description:
Return remainder of a number after dividing by a divisor.
Input:
NUMERIC	value	The value to be divided by the divisor.
NUMERIC	divisor	The divisor value.
Output:
NUMERIC	<Return Value>	The remainder after dividing value by the divisor an integral number of times. If both input arguments are INTEGER, then this result is also INTEGER. Otherwise, this result is REAL.
Error Conditions:
None.


mth_round	( value, ndecimals )


Description:
Return a value rounded to a specified number of decimals.
Input:
REAL	value	The value to be rounded.
INTEGER	ndecimals	Number of decimals.
Output:
REAL	<Return Value>	The input value rounded to the specified number of decimals. Note that with round-off errors, the value may not get exactly rounded.
Error Conditions:
None.

Example:

mth_round( 12.34567, 2 ) yields 12.35

mth_round( 12.34567, 0 ) yields 12.0

mth_round( 12.3457, -1 ) yields 10.0

mth_round( 3.3715, 1 ) yields 3.4000001


mth_sort	( array, dupflag, nleft )


Description:
This function will sort an array of integers, optionally removing all duplicate values.
Input:
INTEGER()	array( )	This value specifies the items to be sorted. This value is used as both an input and an output. The original values passed into the function will be destroyed.
LOGICAL	dupflag	This value specifies, when set to TRUE, that duplicate sorted values will be removed. When this value is set to FALSE, duplicate values will not be removed.
Output:
INTEGER()	array( )	This value returns the sorted items. This value is used as both an input and an output to this function, allowing the original values to be destroyed.
INTEGER	nleft	Number of integers that are in the final sort. Values in the array past this point are undefined. If DUPFLAG is FALSE then this will be the same as the size of the array.
Error Conditions:
None.


mth_sort_column	( matrix, column, ascend )


Description:
Sort a two dimensional integer or real array by one of its columns. The mth_ prefix is required for this routine.
Input:
NUMERIC()	matrix	Matrix of values to sort.
INTEGER	column	Column number within the matrix to sort by. Note that this column number starts from 1 even if the matrix is not based at a lowest dimension of 1.
LOGICAL	ascend	TRUE for an ascending order sort, FALSE for a descending order sort
Output:
NUMERIC()	<Return Value>	Matrix is sorted in place.
Error Conditions:
None.


mth_sort_row	( matrix, row, ascend )


Description:
Sort a two dimensional integer or real array by one of its columns. The mth_ prefix is required for this routine.
Input:
NUMERIC()	matrix	Matrix of values to sort.
INTEGER	row	Row number within the matrix to sort by. Note that this row number starts from 1 even if the matrix is not based at a lowest dimension of 1.
LOGICAL	ascend	TRUE for an ascending order sort, FALSE for a descending order sort
Output:
NUMERIC()	<Return Value>	Matrix is sorted in place.
Error Conditions:
None.


mth_array_search	( array, look4, sorted )


Description:
Search an integer array for a value. The mth_ prefix is required for this routine.
Input:
INTEGER()	array	Integer array of values to search.
INTEGER	look4	Value to find in the array.
LOGICAL	sorted	TRUE if input array is already in ascending sort order. If FALSE then a complete search of the array will be necessary.
Output:
INTEGER	<Return Value>	Position in the array from 1 to n or zero if the value was not found in the array.
Error Conditions:
None.

Example:

Some examples of using PCL math functions:

 max_shear = SQRT( ( sigma_x - sigma_y ) / 2.0)**2 + shear**2 )

eigenroot = n * pi / length

 y = SINR( eigenroot * x ) * ( a * COSR( k * t ) + @

     b * SINR( k * t ))

thru_the_thickness = NINT( thickness/edge)

Note that the trigonometric functions operate on either degrees or radians depending on the last character (D for degrees and R for radians) in the function name. It is a simple matter to write a set of functions which operate in the manner preferred:

FUNCTION   SIN( x )

/* ABSTRACT: Return the SIN of x, where x is in degrees*/

REAL x

RETURN MTH_SIND( x )

END FUNCTION

String Functions

The String functions test, convert, and manipulate PCL strings. String functions are useful for user interface applications and parsing.


str_length	( string )


Description:
Return the current length of a PCL string.
Input:
STRING	string	The string for which to return the length.
Output:
INTEGER	<Return Value>	The current length of the string. Remember that PCL strings are variable length.
Error Conditions:
None.

Example:

string line[40]

line = “ ”

str_length( line ) is now 0

line = line // “testing”

str_length( line ) is now 7


str_maxlength	( string )


Description:
Return the maximum length of a PCL string.
Input:
STRING	string	The string for which to return the maximum length.
Output:
INTEGER	<Return Value>	The maximum length of the string. For a virtual string, this returns the current maximum length. For an unallocated virtual string, the result is currently undefined.
Error Conditions:
None.


str_to_lower	( string )


Description:
Return a copy of the input string with all characters converted to lower case letters.
Input:
STRING	string	The string to convert to lower case. The input string argument is not modified by this call.
Output:
STRING	<Return Value>	The input string converted to lower case.
Error Conditions:
None.


str_to_upper	( string )


Description:
Return a copy of the input string with all characters converted to upper case letters.
Input:
STRING	string	The string to convert to upper case. The input string argument is not modified by this call.
Output:
STRING	<Return Value>	The input string converted to upper case.
Error Conditions:
None.


str_strip_lead	( string )


Description:
Return a copy of the input string with leading blank characters removed.
Input:
STRING	string	The string to strip leading blanks from. The input string argument is not modified by this call.
Output:
STRING	<Return Value>	The input string without any leading blanks.
Error Conditions:
None.


str_strip_trail	( string )


Description:
Return a copy of the input string with trailing blank characters removed.
Input:
STRING	string	The string to strip trailing blanks from. The input string argument is not modified by this call.
Output:
STRING	<Return Value>	The input string without any trailing blanks.
Error Conditions:
None.


str_substr	( string, position, length )


Description:
Return a portion of the input string from the specified position for the specified length.
Input:
STRING	string	The string to extract the substring from. The input string argument is not modified by this call.
INTEGER	position	Starting position in the string where 1 is the first position.
INTEGER	length	Number of characters to extract. If less than or equal to zero, then an empty string is extracted. If more characters are requested than are available in the string from the specified position, only the available characters will be returned.
Output:
STRING	<Return Value>	The extracted substring of the input string.
Error Conditions:
None.


str_assign	( mystring, position, length, substring )


Description:
This function will replace a portion of a string with a another string.
Input:
STRING	mystring[ ]	This value specifies the original string to be modified. This value is used as both an input and output value. The original string will not be preserved.
INTEGER	position	This value specifies the starting place in the input value mystring where the substitution will take place. The first character in the string is at position 1.
INTEGER	length	This value specifies the number of characters to be replaced.
STRING	substring[ ]	This value specifies the string that will be substituted into the input value mystring.
Output:
STRING	mystring[ ]	This value returns the original input value mystring with a portion of the string being replaced with the input value substring. This value is used as both an input and an output value. The original input value mystring will be overwritten.
Error Conditions:
None.


str_index	( string1, string2 )


Description:
Return the position where a string is found within another string.
Input:
STRING	string1	The string within which to find an occurrence of the second string.
STRING	string2	The string to look for within the first string.
Output:
INTEGER	<Return Value>	The position where string2 was found within string1 where 1 is the first position. Zero is returned if the string was not found.
Error Conditions:
None.


str_find_match	( string, chars )


Description:
Return the position where any of a set of characters is found within another string.
Input:
STRING	string	The string within which to find an occurrence of any character in the second string.
STRING	chars	A list of characters to search for within the first string.
Output:
INTEGER	<Return Value>	The position where one of the characters was found within the string where 1 is the first position. Zero is returned if the non of the characters occurred in the string.
Error Conditions:
None.


str_find_nomatch	( string, chars )


Description:
Return the position where any character other than those in a set of characters is found within another string.
Input:
STRING	string	The string within which to find an occurrence of any character not in the second string.
STRING	chars	A list of characters not to search for within the first string.
Output:
INTEGER	<Return Value>	The position where a character was found within the string which is not in the chars string, where 1 is the first position. Zero is returned if the string is only made up of characters within the chars string.
Error Conditions:
None.


str_equal	( string1, string2 )


Description:
Check for an exact match between two strings including exact character case and trailing blanks. Normally the standard PCL == operator would be used which ignores character case and trailing blanks.
Input:
STRING	string1	First string to compare.
STRING	string2	Second string to compare.
Output:
LOGICAL	<Return Value>	TRUE if strings match exactly, FALSE otherwise.
Error Conditions:
None.


str_to_integer	( string [, stat] )


Description:
Convert a string to an integer.
Input:
STRING	string	String to convert to integer value.
Output:
INTEGER	stat	Optional status, zero for success, or the position within the input string which contains the first invalid character.
INTEGER	<Return Value>	Integer value from conversion. Usually zero if the conversion fails.
Error Conditions:
None.


str_to_real	( string [, stat] )


Description:
Convert a string to a real.
Input:
STRING	string	String to convert to real value.
Output:
INTEGER	stat	Optional status, zero for success, or the position within the input string which contains the first invalid character.
REAL	<Return Value>	Real value from conversion. Usually zero if the conversion fails.
Error Conditions:
None.


str_to_logical	( string )


Description:
Convert a string to a logical.
Input:
STRING	string	String to convert to logical value.
Output:
LOGICAL	<Return Value>	Logical value from conversion. This will be TRUE if the first non-blank character of the string is a T, Y, or 1, regardless of case. Otherwise, the value will be FALSE.
Error Conditions:
None.


str_from_integer	( ival )


Description:
Convert an integer to a string.
Input:
INTEGER	ival	Integer to convert to string representation.
Output:
STRING	<Return Value>	String that represents the integer value.
Error Conditions:
None.


str_from_real	( rval )


Description:
Convert a real to a string.
Input:
REAL	rval	Real to convert to string representation.
Output:
STRING	<Return Value>	String that represents the real value. The string may end up being in decimal or in exponential notation.
Error Conditions:
None.


str_from_logical	( lval )


Description:
Convert a logical to a string.
Input:
LOGICAL	lval	Logical to convert to string representation.
Output:
STRING	<Return Value>	String that represents the logical value. The string will be either “TRUE” or “FALSE”.
Error Conditions:
None.


str_datatype	( string )


Description:
Attempt to decipher the type of representation in a string.
Input:
STRING	string	String to decipher.
Output:
STRING	<Return Value>	String representing datatype. Either “INTEGER,” “REAL,” “LOGICAL,” or “STRING.”
Error Conditions:
None.


str_formatc	( string, format, args... )


Description:
Perform a limited C style format conversion into a string. This routine is obsolete but exists for special purposes. Use STRING_WRITE instead.
Input:
STRING	string	Input string.
STRING	format	C Format string with handling of \n, \r, \t, %d, %f, %e, %g, %x, %s, %c, and %%.
unknown	args	Appropriate datatype for format specifiers. Incorrect specifications may cause a crash.
Output:
STRING	<Return Value>	Resultant string from processing format.
Error Conditions:
None.


str_formatf	( string, format, args... )


Description:
Perform a limited C style format conversion into a string. This routine is obsolete but exists for special purposes. Use STRING_WRITE instead.
Input:
STRING	string	Input string.
STRING	format	FORTRAN format string with handling of /, 'string', X, I, F, E, G, and A formats.
unknown	args	Appropriate datatype for format specifiers. Incorrect specifications may cause a crash. Array arguments are allowed.
Output:
STRING	<Return Value>	Resultant string from processing format.
Error Conditions:
None.


str_token	( string, delim, num [, compress ] )


Function;
This function will extract a token or a sequence of characters marked off by a delimiting character or a set of characters from a string.
Input:
STRING	string[ ]	This value specifies the source string from which tokens will be extracted.
STRING	delim[1]	This value specifies the single character token delimiter.
INTEGER	num	This value specifies the ordinal of the token to return from the input value string. This value must be set to at least one. If there are five tokens in the input value string, setting this value to three will cause this function to return the third token.
LOGICAL	compress	This value specifies, when set to TRUE, that empty tokens will be ignored. When this value is set to FALSE, empty tokens caused by multiple delimiters will not be ignored. This value is optional and has a default value of FALSE.
Output:
STRING	<Return Value>	This function returns the token extracted from the input value string. Leading and trailing spaces will be deleted if the delimiter character is not a space.
Error Conditions:
None.


str_abbreviation	( input, abbrev, minmatch )


Description:
Check if a string is a valid abbreviation of another string.
Input:
STRING	input	Input string to check as a valid abbreviation.
STRING	abbrev	String to check input string against.
INTEGER	minmatch	Minimum number of characters that must match for the abbreviation to be considered valid.
Output:
LOGICAL	<Return Value>	TRUE if abbreviation is valid, FALSE otherwise.
Error Conditions:
None.


str_to_ascii	( string [, position ] )


Description:
Return the ASCII integer value for a character within a string.
Input:
STRING	string	String which contains character for which to return ASCII value.
INTEGER	position	Optional position of the character. Default is one for the first character in the string.
Output:
INTEGER	<Return Value>	ASCII integer value or zero if string too small.
Error Conditions:
None.


str_from_ascii	( ascii )


Description:
Return the character represented by an ASCII value.
Input:
INTEGER	ascii	Integer ASCII value to convert to a character.
Output:
STRING	<Return Value>	Single character represented by ASCII value.
Error Conditions:
None.


str_pattern	( string, pattern, options )


Description:
Compare a string against a pattern and return match results.
Input:
STRING	string	String to compare against the pattern.
STRING	pattern	Pattern to check against with wildcards as defined by the options parameter.
INTEGER	options	1 = Unix file type compare where “” matches any number of characters and “?” matches a single character. 2= VMS file type compare where “” matches any number of characters other than a period and “%” matches any single character. 0 = use 1 for unix systems and 2 for VMS systems.
Output:
LOGICAL	<Return Value>	TRUE if the pattern match succeeds. FALSE otherwise.
Error Conditions:
None.


string_newline_count	(string, count)


Description:
This function counts the number of newline characters ( \n ) in a string.
Input:
STRING	string[]	This value specifies the string to look for newline characters.
Output:
INTEGER	count	The number of newline characters in the string.
Error Conditions:
None.


string_newline_position	(string, position)


Description:
This function returns the newline character ( \n ) positions in a string.
Input:
STRING	string[]	This value specifies the string to look for newline characters.
Output:
INTEGER	position[]	The newline character positions in the string.
Error Conditions:
None.

Block I/O Functions

The block I/O package gives access to operating system files in a very efficient manner. The files that block I/O operate on are viewed as fixed record files of a specific block size which is usually some multiple of the file system's disk block size. The block I/O package is often cumbersome to use and is normally not called directly by an application. The Record, Stream, and Virtual I/O utilities all use the Block I/O package. The format of a block I/O file is an MSC proprietary format. A Fortran or other application created file using the block I/O package cannot be accessed.


block_open	( filename, options, nwpb, chan, fsize )


Description:
Open a binary block oriented proprietary format file for access.
Input:
STRING	filename	Operating system name of file.
STRING	options	File open flags. Some set of R, W, N, O, P, and V. See File Utility Functions, 81.
INTEGER	nwpb	Number of words per block to use for the file.
Output:
INTEGER	chan	Channel number to use for subsequent block I/O operations.
INTEGER	fsize	Current file size in bytes if determinable.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


block_close	( chan, options )


Function;
Close a file that was opened for block I/O.
Input:
INTEGER	chan	Channel from a previous block_open call.
STRING	options	Close flags. If “D” is specified, then the file will be deleted after closing.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


block_read	( chan, blknum, nwords, buffer, numread )


Description:
Read a block or blocks from a file opened for block oriented I/O.
Input:
INTEGER	chan	Channel from a previous block_open call.
INTEGER	blknum	Block number to read from the file where zero is the first block.
INTEGER	nwords	Number of words to be read. Normally this is a multiple of the number of words per block.
Output:
INTEGER()	buffer	Buffer area into which data is read. More than NWORDS of data may be returned if NWORDS is not a multiple of the number of words per block.
INTEGER	numread	Number of words actually read.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


block_write	( chan, blknum, nwords, buffer )


Description:
Write a block or blocks to a file opened for block oriented I/O.
Input:
INTEGER	chan	Channel from a previous block_open call.
INTEGER	blknum	Block number to write from the file where zero is the first block.
INTEGER	nwords	Number of words to write.
INTEGER()	buffer	Buffer area from which data is written.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


block_get_name	( chan, fspec, lenfspec )


Description:
Get the operating system filename of a file open for block oriented I/O.
Input:
INTEGER	chan	Channel from a previous block_open call.
Output:
STRING	fspec	File specification of open file.
INTEGER	lenfspec	Length of name returned in FSPEC.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.

File Utility Functions

The file utility functions provide access to the operating system file structure. These functions can look up, delete, and copy files. There are also routines to help parse file specifications into component pieces. The file utility also maintains a path list which is a set of directories that is often used for searching for a file. The PCL !!PATH list is built on top of the file utility path routines.

Several of the file utilities and also the text, record, stream, and block I/O utility open and close routines request an option string for how to find, open, or delete a file. The option string is a set of characters, each of which specifies an option. The order and case of the characters does not matter. Below are the options that can be specified. Many of these options only make sense for certain operations.


N	Create a new file.
O	Open an existing file. If N is given also, the file will be created if it does not already exist.
R	Open the file for read access.
W	Open the file for write access. If R is given also, the file is opened for both reading and writing.
A	Open the file for appending at the end of the file (text_open only).
V	Use version numbers for searching for or creating the file.
P	Search the file utilities path to find the file.
L	Lock the file for exclusive access (not yet implemented).
S	Use scratch directory (file_unique_name only).
D	Delete the file after close (close routines only).

The file and I/O utilities also have a limited amount of support for file version numbers. For UNIX and Windows NT systems, a version number is specified by appending a period and a number, one or greater, to the filename. If the version number is less than 10, a leading zero is added to provide better sorting for UIMS and UNIX file sorting. The version utilities will recognize a versioned file with or without the leading zero.

An example of an open options specification for opening an already existing file for read access only is given below.

status = text_open (filename, “OR”, 0, 0)


file_add_path	( where, newpath )


Description:
Add a path to the path list.
Input:
INTEGER	where	Position to insert path. Zero inserts at the start (after current directory), 1 inserts after the first path, and so on.
STRING	newpath	New directory specification to add to the path list.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


file_append_version	( version, nzeros, fspec )


Description:
Append a version number to a file specification only if there is not already a version number in the specification. This is a utility routine which will not normally be called by the user. Use file_build_fname instead.
Input:
INTEGER	version	Version number or zero for no version.
INTEGER	nzeros	Number of leading zeros to add to version number.
STRING	fspec	Original file specification.
Output:
STRING	fspec	Modified file specification.
Error Conditions:
None.


file_build_fname	( dir, base, ext, options, filespec )


Description:
Create a full file specification given its component parts.
Input:
STRING	dir	Directory portion of file specification.
STRING	base	Base filename portion.
STRING	ext	Extension for filename.
STRING	options	Options of N, O, P, or V. See File Utility Functions, 81.
Output:
STRING	filespec	Resultant file specification.
Error Conditions:
None.


file_create_directory	( dirname, access )


Description:
Create a directory.
Input:
STRING	dirname	Path to directory to create. If multiple directories need to be created for the path, they will be.
INTEGER	access	Unix style access permissions for new directories. This value is normally an octal number which is hard to represent in PCL. The easiest way to specify a protection such as 755 is to use the expression (764+58+5). Using zero gives no access to the directory, using 764+78+7 gives full access to the directory.
Output:
INTEGER	<Return Value>	Zero for success. If the directory already exists, the call is considered successful.
Error Conditions:
None.


file_delete	( filespec )


Description:
Delete an operating system file.
Input:
STRING	filespec	File to delete. The path will not be searched for the file.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


file_delete_path	( oldpath )


Description:
Remove a path from the path list.
Input:
STRING	oldpath	Directory specification to remove from the path.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


file_executable	( filespec )


Description:
Return whether or not a specified file has execute permission.
Input:
STRING	filespec	File specification to check.
Output:
LOGICAL	<Return Value>	True for execute permission, False if no execute permission.
Error Conditions:
None.
Side Effects:
Warning.	If the operating system can’t determine execute permission, this function will normally return True.


file_exists	( filespec, options )


Description:
Check to see if a file exists.
Input:
STRING	filespec	File to look up.
STRING	options	Option flags of P or V. See File Utility Functions, 81.
Output:
LOGICAL	<Return Value>	TRUE if file exists. FALSE if file could not be found.
Error Conditions:
None.


file_exists_local	( filespec )


Description:;
Check to see if a file exists in the current directory. Normally, the “file_exists” function should be used with empty options instead of this routine.
Input:
STRING	filespec	File to look up.
Output:
LOGICAL	<Return Value>	TRUE if file exists. FALSE if file could not be found.
Error Conditions:
None.


file_exists_version	( filespec, version, nzeros )


Description:
Find the highest version of a file in the current directory.
Input:
STRING	filespec	File to look up without version specified.
Output:
INTEGER	version	Version number found or zero if no versions exists but the file exists without any version.
INTEGER	nzeros	Number of leading zeros that were found in the version number.
LOGICAL	<Return Value>	TRUE if file exists. FALSE if file could not be found.
Error Conditions:
None.


file_expand_home	( inspec, outspec )


Description:
Expand any “~” home directory syntax in the file specification.
Input:
STRING	inspec	Input file specification.
Output:
STRING	outspec	File specification with expanded home syntax.
Error Conditions:
None.


file_get_bfname	( filespec, basename )


Description:
Extract the base filename given a file specification (without versions).
Input:
STRING	filespec	Input file specification.
Output:
STRING	basename	Base filename.
Error Conditions:
None.


file_get_dfname	( filespec, directory )


Description:
Extract the directory specification given a file specification.
Input:
STRING	filespec	Input file specification.
Output:
STRING	directory	Directory specification.
Error Conditions:
None.


file_get_efname	( filespec, extension )


Description:
Extract the extension specification given a file specification (without versions).
Input:
STRING	filespec	Input file specification.
Output:
STRING	extension	Extension specification.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


file_get_filespec	( inspec, options, outspec )


Description:
Get a file specification that matches the specified input specification and options.
Input:
STRING	inspec	Input file specification.
STRING	options	Option string containing any of N, O, P, or V. See File Utility Functions, 81.
Output:
STRING	outspec	Output file specification.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


file_get_next_path	( ipath, path )


Description:
Iteratively retrieve entries from the path list.
Input:
INTEGER	ipath	Set to zero on first call. Pass return result back in on subsequent calls.
Output:
STRING	path	Next entry from the path list. The current directory path is returned as an empty string.
INTEGER	<Return Value>	Minus one if no more paths left. Otherwise use this value for the next call to file_get_next_path.
Error Conditions:
None.


file_get_p3_home	( path )


Description:
Return directory path for Patran “home” directory.
Input:
None.
Output:
STRING	path	Path to Patran “home” directory.
INTEGER	<Return Value>	Status, zero for success.
Error Conditions:
None.


file_init_path	( option )


Description:
Initialize the path list for use.
Input:
INTEGER	option	Zero to initialize if not already done. One to clear all entries from the path. Two to reset the path back to the initial default path setting.
Output:
None.
Error Conditions:
None.


file_list_end	( chan )


Description:
Iteratively retrieve entries from the path list.
Input:
INTEGER	chan	Value from file_list_start.
Output:
INTEGER	<Return Value>	Status, zero for success, else error code.
Error Conditions:
None.

Example:

INTEGER status, chan
STRING fname [256]

status = file_list_start ( “/tmp”, “patran.ses.*”, chan )
IF ( status == 0 ) THEN
		WHILE ( file_list_next ( chan, fname ) == 0 )
			xf_write_comment ( fname )
		END WHILE
			file_list_end ( chan )
END IF


file_list_next	( chan, fname )


Description:
Iteratively retrieve entries from the directory using the optional filter specified in file_list_start.
Input:
INTEGER	chan	Value from file_list_start that indicates the directory and filter..
Output:
STRING	fname	The next file in the indicated directory that matches the specified filter.
INTEGER	<Return Value>	Status, zero for success, -1 for end of list, else error code.
Error Conditions:
None.


file_list_start	( directory, filter, chan )


Description:
Initialize a file directory search for files matching a pattern. This routine initializes the search, file_list_next gets each name, and file_list_end cleans up.
Input:
STRING	directory	Name of directory to search. A “.” will cause the current directory to be searched.
STRING	filter	File name qualifier. Only * and ? are guaranteed to work.
Output:
INTEGER	chan	Return value to use on subsequent calls to file_list_next and file_list_end.
INTEGER	<Return Value>	Status, zero for success, else error code.
Error Conditions:
None.
Side Effects:
Memory.	Be sure to call file_list_end to match file_list_start or memory structures may not be freed.


file_readable	( filespec )


Description:
Check if read access is possible to a file.
Input:
STRING	filespec	File to check for read access.
Output:
LOGICAL	<Return Value>	TRUE if reading is possible, otherwise FALSE.
Error Conditions:
None.


file_writeable	( filespec )


Description:
Check if write access is possible to a file.
Input:
STRING	filespec	File to check for write access.
Output:
LOGICAL	<Return Value>	TRUE if writing is possible, otherwise FALSE.
Error Conditions:
None.


file_unique_name	( prefix, options, outspec )


Description:
Generate a unique name for a file (usually a scratch work file).
Input:
STRING	prefix	Prefix string for file, may be empty.
STRING	options	Option “S” for create in temp directory, or empty for create in current directory.
Output:
STRING	outspec	Output file specification.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


file_copy	( source, dest )


Description:
Copy an operating system file.
Input:
STRING	source	Name of existing source file.
STRING	dest	Name of new destination file which must not exist.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


file_query_remote	( filename )


Description:
Determine whether or not a file resides on a remote file system.
Input:
STRING	filename	File to check.
Output:
INTEGER	<Return Value>	Zero for file is remote, otherwise message code for file local or does not exist.
Error Conditions:
None.

Record I/O Utility Functions

The record input/output package provides a set of routines to read and write files consisting of complex records of variable length mixed data types. Integers, logicals, reals, strings, and 1, 4, or 8 bit integers are all supported. Record I/O files are self defining with the data in the file specifying the datatypes and lengths of the data in the file. This means that a Record I/O file can be processed by a program which does not know the contents of the file, and makes it easy to expand the capabilities of an application without obsoleting existing files. The Record I/O package is built on top of the Stream I/O package.

Each record is defined as having a typecode followed by any combination of datatypes. A typecode is a positive integer that is defined by the application which usually denotes what kind of data is represented by the record. An example record might have a typecode of 100 followed by 3 integers, 100 reals, 2 more integers, 20 characters, and a logical. When reading in a record, the application can query the next datatype and data count in the record.

Since the Record I/O package is built on top of the Stream I/O package, the creation and modification dates of the file are retained. The file also has a file type code and a character description. The performance of the Record I/O should be good since at the bottom layer buffered block I/O is performed.

Generally, to create a Record I/O file, first call record_open_new to create the file. Next, start a new record with record_begin_write passing the typecode for the record. Then call record_write_rechead passing the datatype and count for the next field in the record. Then call the appropriate record_write_xxx routine for the datatype that is being written. Repeat the record_write_rechead and record_write_xxx calls for each field in the record, and then call record_end_rw to terminate the record. Continue writing records as desired, and call record_close when with the file. For several simple record types, there are routines of the name record_write_rec_xxx which will do much of the work automatically.

To read a Record I/O file, first call record_open_old to open the file, then read the next record header with record_begin_read which will return the typecode of the record. Now call record_read_rechead which returns the datatype and count of the next field in the record followed by a call the appropriate record_read_xxx routine to read the data. Close the file with record_close when done.


record_open_new	( filename, options, filecode, description, chan )


Description:
Create and open a new record I/O file.
Input:
STRING	filename	Name of file to open.
STRING	options	Open options of R, W, P, or V. See File Utility Functions, 81.
INTEGER	filecode	Integer value for the filetype of the new file. Ideally this should be a unique number for each kind of file that is created.
STRING	description	A informational text description of the file.
Output:
INTEGER	chan	Value to use for subsequent operations to this file.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_open_old	( filename, options, chan, filecode, description )


Description:
Open an existing record I/O file.
Input:
STRING	filename	Name of file to open.
STRING	options	Open options of R, W, P, or V. See File Utility Functions, 81.
Output:
INTEGER	chan	Value to use for subsequent operations to this file.
INTEGER	filecode	Integer value that represents kind of file and is set by the record_open_new routine.
STRING	description	Description of the file.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_close	( chan, options )


Description:
Close a file opened for record I/O.
Input:
INTEGER	chan	Channel from the record I/O open routine.
STRING	options	Close options. Either “D” to delete the file after close or an empty string.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_get_name	( chan, fspec, lenfspec )


Description:
Return the file specification for an open record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
Output:
STRING	fspec	Filename of open record I/O file.
INTEGER	lenfspec	Length of the file specification.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_writerec_chars	( chan, typecode, count, buffer )


Description:
Write a record containing only character data to the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
INTEGER	typecode	Typecode for the record.
INTEGER	count	Number of characters to write from the string.
CSTRING	buffer	String to write to record file.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_writerec_intchr	( chan, typecode, icount, ibuffer, ccount, cbuffer )


Description:
Write a record containing only integer and character data to the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
INTEGER	typecode	Typecode for the record.
INTEGER	icount	Number of integers to write to the record.
INTEGER()	ibuffer	Integer data to write.
INTEGER	ccount	Number of characters to write from the string.
CSTRING	cbuffer	String to write to record file.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_writerec_ints	( chan, typecode, count, buffer )


Description:
Write a record containing only integer data to the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
INTEGER	typecode	Typecode for the record.
INTEGER	count	Number of integers to write to the record.
INTEGER()	buffer	Integer data to write.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_writerec_reals	( chan, typecode, count, buffer )


Description:
Write a record containing only integer data to the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
INTEGER	typecode	Typecode for the record.
INTEGER	count	Number of reals to write to the record.
REAL	buffer()	Real data to write.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_begin_write	( chan, typecode )


Description:
Start the writing of a complex record in the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
INTEGER	typecode	Typecode for the record.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_begin_read	( chan, typecode )


Description:
Start the reading of a record from the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
Output:
INTEGER	typecode	Typecode for the record. Will be -1 for the end of the file.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_end_rw	( chan )


Description:
Complete the read or complex write of a record in the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_write_rechead	( chan, format, count )


Description:
Start the next field in writing a complex record to the Record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
INTEGER	format	Datatype that will be written. Types defined are: 1=integer, 2=real, 3=char, 4=double real (not from PCL), 5=half integer, 6=byte integer, 7=4bit integer, 8=1bit integer, 9=logical, 10=pointer.
INTEGER	count	Number of items of the specified format that will make up the data field.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_read_rechead	( chan, format, count )


Description:
Start the read of the next field from the current record of the Record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
Output:
INTEGER	format	Datatype that is available next. Types defined are: 1=integer, 2=real, 3=char, 4=double real (not from PCL), 5=half integer, 6=byte integer, 7=4bit integer, 8=1bit integer, 9=logical, 10=pointer.
INTEGER	count	Number of items of the specified format that are available in the field.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_write_ints	( chan, numitems, i_buffer )


record_write_reals	( chan, numitems, r_buffer )


record_write_chars	( chan, numitems, c_buffer )


record_write_halfints	( chan, numitems, h_buffer )


record_write_int8bits	( chan, numitems, i8_buffer )


record_write_int4bits	( chan, numitems, i4_buffer )


record_write_intbits	( chan, numitems, i1_buffer )


record_write_logicals	( chan, numitems, l_buffer )


record_write_pointers	( chan, numitems, p_buffer )


Description:
Start the read of the next field from the current record of the Record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
INTEGER	numitems	Number of items that will be written from the buffer given.
INTEGER()	i_buffer	Data of integers to write.
REAL()	r_buffer	Data of reals to write.
STRING	c_buffer	String data to write.
INTEGER()	h_buffer	Data of half integers, one per integer, to write.
INTEGER()	i8_buffer	Data of 8 bit integers, one per integer, to write.
INTEGER()	i4_buffer	Data of 4 bit integers, one per integer, to write.
INTEGER()	i1_buffer	Data of 1 bit integers, one per integer, to write.
LOGICAL()	l_buffer	Data of logicals to write.
INTEGER()	p_buffer	Data of pointers, one per integer, to write.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_read_ints	( chan, numitems, i_buffer )


record_read_reals	( chan, numitems, r_buffer )


record_read_chars	( chan, numitems, c_buffer )


record_read_halfints	( chan, numitems, h_buffer )


record_read_int8bits	( chan, numitems, i8_buffer )


record_read_int4bits	( chan, numitems, i4_buffer )


record_read_intbits	( chan, numitems, i1_buffer )


record_read_logicals	( chan, numitems, l_buffer )


record_read_pointers	( chan, numitems, p_buffer )


Description:
Read all or part of the current field of the current record of the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
INTEGER	numitems	Number of items to read into the specified buffer.
Output:
INTEGER()	i_buffer	Integer data read in.
REAL()	r_buffer	Real data read in.
STRING	c_buffer	String data read in.
INTEGER()	h_buffer	Half integer data read in, one per integer.
INTEGER()	i8_buffer	Eight bit integer data read in, one per integer.
INTEGER()	i4_buffer	Four bit integer data read in, one per integer.
INTEGER()	i1_buffer	One bit integer data read in, one per integer.
LOGICAL()	l_buffer	Logical data read in.
INTEGER()	p_buffer	Pointer data read in, one per integer.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_get_position	( chan, position )


Description:
Get a pointer value for the current position in the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
Output:
INTEGER	position	Pointer value in internal format.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_set_position	( chan, position )


Description:
Set the current position in the record I/O file using either a previous pointer value or the special value of zero or minus one.
Input:
INTEGER	chan	Channel from the record I/O open routine.
INTEGER	position	Start of record pointer from previous record_get_position call or zero for start of the file or minus one for end of the file.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_get_header	( chan, cdatetime, mdatetime )


Description:
Get creation/modification dates for the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
Output:
STRING	cdatetime	Creation date of file in format: yyyymmddhhmmss.
STRING	mdatetime	Modify date of file in format: yyyymmddhhmmss.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


record_update	( chan )


Description:
Attempt to force the disk file to be up to date for the record I/O file.
Input:
INTEGER	chan	Channel from the record I/O open routine.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.

Stream I/O File Utility Functions

The stream input/output package provides a method of reading and writing a binary file treating it as a stream of bytes and words with no record format imposed on it. Support exists for integer, real, and character data. The stream concept implies that whether 2 integer words are written 100 times, or 100 integer words 2 times, the same result is received.

Generally, a file is opened with stream_open, write to it with stream_write_int, stream_write_real, or stream_write_char, read from it with stream_read_int, stream_read_real, or stream_read_char, and close it with stream_close. Data can be skipped with stream_skip_int, stream_skip_real, or stream_skip_char. Some kinds of random access can be performed using stream_get_position and stream_set_position. The stream_update call is used to flush data to disk. File header information, which includes the filecode, description, creation and modification dates can be read and possibly modified with stream_get_header and stream_set_header.


stream_open	( filename, options, chan )


Description:
Create or open a new or existing stream I/O file.
Input:
STRING	filename	Name of file to open/create.
STRING	options	Open options of N, O, R, W, P, or V. See File Utility Functions, 81.
Output:
INTEGER	chan	Channel number to use for subsequent stream I/O operations on this file.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_close	( chan, options )


Description:
Close a file opened for stream I/O.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
STRING	options	Close options. Use “D” to delete the file after closing or else use an empty string.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_get_name	( chan, fspec, lenfspec )


Description:
Get the name of a file that is open for stream I/O.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
Output:
STRING	fspec	Name of the file.
INTEGER	lenfspec	Length of the file specification returned.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_get_header	( chan, filetype, description, createdate, modifydate, recordinfo )


Description:
Get header information associated with an open stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
Output:
INTEGER	filetype	Filetype integer set from a stream_set_header call.
STRING	description	Description string from a stream_set_header call.
STRING	createdate	Creation date in format: yyyymmddhhmmss.
STRING	modifydate	Modify date in format: yyyymmddhhmmss.
INTEGER(5)	recordinfo	Application use data words.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_set_header	( chan, filetype, description, recordinfo )


Description:
Set some header information for a stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	filetype	Filetype integer, application defined.
STRING	description	Description string, application defined.
INTEGER(5)	recordinfo	Application defined data words.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_get_position	( chan, position )


Description:
Get the current position in the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
Output:
INTEGER	position	Position returned in internal format.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_set_position	( chan, position )


Description:
Set current position in the stream file to the beginning of the file or to a previously saved position.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	position	Zero for beginning of file or a value returned from a previous call to stream_get_position.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_read_int	( chan, numtoread, buffer )


Description:
Read integers from the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	numtoread	Number of integers to read.
Output:
INTEGER()	buffer	Integer data read in by the call.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_read_real	( chan, numtoread, buffer )


Description:
Read reals from the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	numtoread	Number of reals to read.
Output:
REAL()	buffer	Real data read in by the call.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_read_char	( chan, numtoread, buffer )


Description:
Read characters from the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	numtoread	Number of characters to read.
Output:
STRING	buffer	Character data read from stream I/O file.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_write_int	( chan, numtowrite, buffer )


Description:
Write integers to the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	numtowrite	Number of integers to write out.
INTEGER()	buffer	Data to write out to the file.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_write_real	( chan, numtowrite, buffer )


Description:
Write reals to the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	numtowrite	Number of reals to write out.
REAL()	buffer	Data to write out to the file.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_write_char	( chan, numtowrite, buffer )


Description:
Write character data to the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	numtowrite	Number of characters to write out.
STRING	buffer	Character data to write.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_skip_int	( chan, numtoskip )


Function;
Skip over integers in the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	numtoskip	Number of integers to skip.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_skip_real	( chan, numtoskip )


Description:
Skip over reals in the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	numtoskip	Number of reals to skip.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_skip_char	( chan, numtoskip )


Description:
Skip over character data in the stream I/O file.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
INTEGER	numtoskip	Number of characters to skip.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


stream_update	( chan )


Description:
Attempt to force all output to be up to date on disk.
Input:
INTEGER	chan	Channel from a previous call to stream_open.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.

String I/O Conversion Utility Functions

The string input/output routines are used when complex formatting of data to or from a character string is needed. A string of data with a format specifier can be passed to string_read to convert the character data to a list of integers, reals, and character strings. A set of integers, reals, and character strings can be converted to a string using string_write.

Output Format Strings

Below is a description of output format strings, that is format strings that are used to convert integer, real, and string data to a formatted output. The format string is a simple character string which contains both raw text to output, and format specifiers, enclosed by a set of percent characters, which control how data items are formatted and output. Following is a description of each type of format specifier. The percent and upper case characters in the format specifiers are treated literally. The lowercase letters, “r”, “m”, “n”, or “p” are to be replaced with an unsigned integer constant, or an asterisk, and are always optional. An asterisk denotes that the value for the operation should be taken from the next element of the integer data array. The lowercase letter “f” is replaced by single uppercase letters for options, and is also optional. Currently defined is “L” for left justified, “R” for right justified(default), and “C” for compressed (E and G format only).


%%	The simplest form of format specifier is a double percent to produce a single percent in the final output.
%rIm.nf%	Integer specifier. This format specifier takes the next integer value from the integer data array for formatting. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters necessary to hold the integer is used. The value of “n” is used to specify that many digits should be produced at a minimum, using leading zeros if necessary. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the integer data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion. The exact format produced is an optional minus sign followed by one or more digits.
%rXm.nf%	Integer hex specifier. This format specifier takes the next integer value from the integer data array for formatting as a hexadecimal number. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters necessary to hold the conversion is used. The value of “n” is used to specify that many digits should be produced at a minimum, using leading zeros if necessary. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the integer data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion. The exact format produced is one or more hexadecimal digits.
%rFm.nf%	Fixed float specifier. This format specifier takes the next real value from the real data array for formatting in fixed point notation. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters necessary to hold the conversion is used. The value of “n” is the number of decimal digits to produce. If omitted, then all significant digits will be produced. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the real data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion. The exact format produced is an optional minus sign followed by zero or more digits, a decimal point, and zero or more digits. At least one digit will precede or follow the decimal point.
%rEm.n.pf%	Exponential float specifier. This format specifier takes the next real value from the real data array for formatting in scientific exponential notation. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters necessary to hold the conversion is used. The value of “n” is the number of decimal digits to produce. If omitted, then all significant digits will be produced. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the real data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion.
%rGm.n.pf%	General float specifier. This format specifier takes the next real value from the real data array for formatting in either F or E format. The format used depends on the value of the number to convert. In general, if the exponent is small, the F format will be used, otherwise the E format is used. See the descriptions of the F and E formats.
%rAmf%	String specifier. This format specifier takes the next string value from the character data array for formatting. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters in the string is used. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the character data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion. Use the “L” option for “f” for left justification of the string.
%rW%	White space specifier. This format specifier causes a blank character to be output. The value of “r” is a repeat count for multiple blanks.
%rN%	New Line specifier. This format specifier causes a new line to be started. The previous line is output as is, and formatting starts at column one of the new line. The value of “r” is a repeat count for skipping multiple lines. If output is to a string, then newline characters will be written to the string.
%r(xxx)%	Repeat specifier. Enclosed within the parentheses is a secondary format string, complete with its own percent characters, which is repeated the number of times specified in the “r” repeat count. Repeat specifiers can be nested as desired.

Input Format Strings

Input format strings, that is format strings that are used to convert formatted input to integer, real, and string data are very similar to output format strings. The format string is a simple character string which contains format specifiers, enclosed by a set of percent characters, which control how data items are formatted and output. Text outside of the format specifiers is ignored. Following is a description of each type of format specifiers. The percent and upper case characters in the format specifiers are treated literally. The lowercase letters, “r”, “m”, or “n” are to be replaced with an unsigned integer constant, or an asterisk, and are always optional. An asterisk denotes that the value for the operation should be taken from the next element of the integer data array.


g %rIm%	Integer specifier. This format specifier converts input to an integer value and stores it in the next element of the integer data array. The value of “m” is the length of the field to process. If “m” is omitted, then the conversion will take place up to the next space, comma, or end of line. The value of “r” is a repeat count which causes the specifier to be used that number of times.
%rXm%	Integer hex specifier. This format specifier converts input of a hexadecimal representation to an integer value and stores it in the next element of the integer data array. The value of “m” is the length of the field to process. If “m” is omitted, then the conversion will take place up to the next space, comma, or end of line. The value of “r” is a repeat count which causes the specifier to be used that number of times.
%rFm%	Fixed float specifier. This format specifier converts input of a floating point representation to a real value and stores it in the next element of the real data array. This conversion will accept both fixed and exponential format numbers. The value of “m” is the length of the field to process. If “m” is omitted, then the conversion will take place up to the next space, comma, or end of line. The value of “r” is a repeat count which causes the specifier to be used that number of times.
%rEm%	Exponential float specifier. Same as the fixed float specifier.
%rGm%	General float specifier. Same as the fixed float specifier.
%rAm%	String specifier. This format specifier converts input to sting value and stores it in the next element of the string data array. The value of “m” is the length of the field to process. If “m” is omitted, then the conversion will take place up to the next space, comma, or end of line. The value of “r” is a repeat count which causes the specifier to be used that number of times.
%rW%	White space specifier. This format specifier causes the next character of the input to be skipped and ignored. The value of “r” is a repeat count for multiple blanks.
%rN%	New Line specifier. This format specifier causes a new line to be started for input. Any remaining input on the previous line is ignored. The value of “r” is a repeat count for skipping multiple lines.
%Of%	Option specifier. The value of “f” is a single character option to set. Currently defined options are “F” for fixed Fortran- style inputting or “V” for variable style inputting. The initial default is “V.” The setting remains for the remainder of the call unless overridden with another %O%. With fixed style formatting, blank fields are interpreted as zeros, and input will not continue to the next line during this call unless a %N% occurs.
%r(xxx)%	Repeat specifier. Enclosed within the parentheses is a secondary format string, complete with its own percent characters, which is repeated the number of times specified in the “r” repeat count.

The INTS, REALS, and CHARS parameters to the formatting routines are somewhat flexible. If only passing a single value, it can be passed directly instead of having to use an array. If not using the parameter at all, pass a constant for the parameter.


string_read	( string, fmt, ints, reals, chars )


Description:
Read formatted record of mixed data from a string variable.
Input:
STRING	string	Character string from which the conversion takes place.
STRING	fmt	Format string governing how conversion is done. See Input Format Strings, 123 for details.
Output:
INTEGER()	ints	Integer array of data filled in by the read.
REAL()	reals	Real array of data filled in by the read.
STRING[]()	chars	Character array of data filled in by the read.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.

Example:

INTEGER stat, ints(3); REAL reals(3); STRING chars[10](3)

stat = string_read( “20 30,40 1.75 22 3E-1 Test one two three”, @

%3I%%3F%%3A%”, ints, reals, chars )

Yields: ints = 20, 30, 40

reals = 1.75, 22, .3

chars = “Test”, “one”, “two”


string_write	( fmt, ints, reals, chars, string )


Description:
Write formatted records of mixed data into a string variable.
Input:
STRING	fmt	Format string governing how conversion is done. See Output Format Strings, 121 for details.
INTEGER()	ints	Integer array of data to convert.
REAL()	reals	Real array of data to convert.
STRING[]()	chars	String array of data to convert.
Output:
STRING	string	Character string which receives converted data.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.

Example:

INTEGER stat, ints(2) = 100, 200; STRING out[80]

stat = string_write( “Test ival is %I% and rval is %F% for %A% # %I%”, @

		ints, 3.17, “Trial”, out )

Yields:	out = “Test ival is 100 and rval is 3.17 for Trial # 200”

INTEGER stat, ints(9) = 2, 4, 6, 3, 3, 1, 2, 3, 2

REAL reals(5) = 1., 2., 3., 4., 5. ; STRING out[80]

stat = string_write( “%2(That’s %*I% and %*G%.)%”, @

		ints, reals, “”, out )

Yields:	out = “That’s 4 6 and 1.0 2.0 3.0.That’s 1 2 3 and 4.0 5.0.”

Text File I/O Utility Functions

The text input/output routines are used to create or read operating system readable text files. Use text_open to open/create the file by filename, and a “channel” number is returned which is used for all subsequent calls pertaining to that file. Read or write simple string records with text_read_string and text_write_string. Read or write more complex formatted records with text_read and text_write. A limited amount of random access of the file can be done by using text_get_position and text_set_position. Lastly, get the name of the open file using text_get_name.


text_open	( filespec, options, lrecl, maxrecs, chan )


Description:
Open a text file for the Text I/O package.
Input:
STRING	filespec	Filename of file to open.
STRING	options	Open options of N, O, A, R, W, P, or V. See File Utility Functions, 81.
INTEGER	lrecl	Maximum record length for the file if known. Use zero if not known.
INTEGER	maxrecs	Maximum number of records that the file will contain if known. Use zero if not known.
Output:
INTEGER	chan	Channel value to use for subsequent text I/O operations.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


text_close	( chan, options )


Description:
Close a text file that was previously opened with text_open.
Input:
INTEGER	chan	Channel from a previous call to text_open.
STRING	options	Close options. Use “D” to delete the file after closing or an empty string otherwise.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


text_flush	( chan )


Description:
Attempt to flush any output to the disk for the specified text I/O file.
Input:
INTEGER	chan	Channel from a previous call to text_open.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


text_get_name	( chan, fspec, lenfspec )


Description:
Get the filename associated with an open text I/O file.
Input:
INTEGER	chan	Channel from a previous call to text_open.
Output:
STRING	fspec	File specification associated with text I/O file.
INTEGER	lenfspec	Length of string returned in fspec.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


text_read_string	( chan, line, lenline )


Description:
Read a single record into a string from a text I/O file.
Input:
INTEGER	chan	Channel from a previous call to text_open or zero to read from standard input (xterm window).
Output:
STRING	line	Line read in from the text file.
INTEGER	lenline	Length of the line that was read in.
INTEGER	<Return Value>	Zero for success, minus one for end of file, else error message code.
Error Conditions:
None.


text_write_string	( chan, line )


Description:
Write a single record from a string to a text I/O file.
Input:
INTEGER	chan	Channel from a previous call to text_open or zero to write to standard output (xterm window).
STRING	line	Line to write to the text file.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.

See Input Format Strings, 123 for more information.


text_read	( chan, fmt, ints, reals, chars )


Description:
Read formatted records of mixed data from an open text I/O file.
Input:
INTEGER	chan	Channel from a previous call to text_open or zero to write to standard output (xterm window).
STRING	fmt	Format string governing how conversion is done.
Output:
INTEGER()	ints	Integer data converted from the read.
REAL()	reals	Real data converted from the read.
CSTRING[]()	chars	String data converted from the read.
INTEGER	<Return Value>	Zero for success, minus one if end of file, else error message code.
Error Conditions:
None.


text_write	( chan, fmt, ints, reals, chars )


Description:
Write formatted records of mixed data to a text I/O file.
Input:
INTEGER	chan	Channel from a previous call to text_open or zero to write to standard output (xterm window).
STRING	fmt	Format string governing how conversion is done.
INTEGER()	ints	Integer data to convert for the write.
REAL()	reals	Real data to convert for the write.
CSTRING[]()	chars	String data to convert for the write.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


text_get_position	( chan, position )


Description:
Get the current position in the text file for later use with text_set_position.
Input:
INTEGER	chan	Channel from a previous call to text_open.
Output:
INTEGER	position	Internal representation of the current position in the text I/O file.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


text_set_position	( chan, position )


Description:
Set the current position in the text file to the beginning of the file, the end of the file, or to a position previously saved with text_get_position.
Input:
INTEGER	chan	Channel from a previous call to text_open.
INTEGER	position	Zero for beginning of file, minus one for end of file, or a value previously returned by a call to text_get_position.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


text_truncate	( chan )


Description:
Truncate the text file at the current position thereby deleting any records that follow this position. The file must have been opened for write access.
Input:
INTEGER	chan	Channel from a previous call to text_open.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


text_get_file_size	( chan, bytesize )


Description:
Return the size of the file in bytes.
Input:
INTEGER	chan	Channel from a previous call to text_open.
Output:
INTEGER	bytesize	Size of the file in bytes.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


text_file_query	( filnam, options, recnum, startc, endc, lowval, hival )


Description:
Determine if a file contains character text when it is known that a portion of a record of the file contains a text representation of an integer value.
Input:
STRING	filnam	File to check.
STRING	options	Open options of P, or V. See File Utility Functions, 81.
INTEGER	recnum	Record of the file which contains the known integer value where record 1 is the first record of the file.
INTEGER	startc	Starting character position in the record for the known integer value where 1 is the first position.
INTEGER	endc	Ending character position in the record for the known integer value.
INTEGER	lowval	Lowest acceptable value for the integer.
INTEGER	hival	Highest acceptable value for the integer.
Output:
LOGICAL	<Return Value>	TRUE if the file exists, can be read, and has a text representation of an integer in the specified record and columns that is within the specified bounds. Otherwise the result is returned FALSE.
Error Conditions:
None.

Virtual I/O Scratch File Utility Functions

The virtual I/O routines are used when large amounts of working storage is needed and performance is important. If an application always tries to allocate virtual memory for its algorithm, it is limited by the amount of memory and swap space allocated on the particular machine. The virtual file package attempts to work around this problem by automatically spilling data onto disk as necessary while still maintaining as much of the work area in memory as makes sense. To accomplish this, the virtual file package treats the work area as a stream file made up of integers, reals, and characters. The calls to the virtual file package are almost identical to those in the stream file package.


virtual_open_scratch	( chan )


Description:
Create and open a virtual scratch file.
Input:
None.
Output:
INTEGER	chan	Channel number to be used for subsequent operations on the virtual file.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_close	( chan )


Description:
Close a virtual scratch file.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_write_int	( chan, numtowrite, buffer )


Description:
Write integers to a virtual file.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	numtowrite	Number of integers to write from the buffer.
INTEGER()	buffer	Buffer containing integers to write.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_write_real	( chan, numtowrite, buffer )


Description:
Write reals to a virtual file
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	numtowrite	Number of reals to write from the buffer.
REAL()	buffer	Buffer containing reals to write.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_write_char	( chan, numtowrite, buffer )


Description:
Write characters to a virtual file.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	numtowrite	Number of characters to write from the buffer.
STRING	buffer	Buffer containing characters to write.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_read_int	( chan, numtoread, buffer )


Description:
Write integers from a virtual file.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	numtoread	Number of integers to read into the buffer.
Output:
INTEGER()	buffer	Area to read integers into.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_read_real	( chan, numtoread, buffer )


Description:
Read real data from a virtual file.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	numtoread	Number of reals to read into the buffer.
Output:
REAL()	buffer	Area to read reals into.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_read_char	( chan, numtoread, buffer )


Description:
Read character data from a virtual file.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	numtoread	Number of characters to read into the buffer.
Output:
STRING	buffer	Area to read characters into.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_skip_int	( chan, numtoskip )


Description:
Skip over integer data in a virtual file.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	numtoskip	Number of integers to skip over.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_skip_real	( chan, numtoskip )


Description:
Skip over real data in a virtual file.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	numtoskip	Number of reals to skip over.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_skip_char	( chan, numtoskip )


Description:
Skip over character data in a virtual file.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	numtoskip	Number of characters to skip over.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_get_position	( chan, position )


Description:
Get the current position in the virtual scratch file for later use with virtual_set_position.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
Output:
INTEGER	position	Internal position to use in a later call to virtual_set_position.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


virtual_set_position	( chan, position )


Description:
Set the current position in the virtual scratch file to the beginning of the file or to a position previously retrieved with a call to virtual_get_position.
Input:
INTEGER	chan	Channel number returned by a previous call to virtual_open_scratch.
INTEGER	position	Zero to set position to the beginning of the file or a position previously returned by virtual_get_position.
Output:
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.

Console I/O Functions

The console I/O functions are used to display messages to the terminal window, history window, and session file.


xf_error_start	( mess )


Description:
Start the reporting of an error message.
Input:
STRING	mess	First line of error message to report.
Output:
None.
Error Conditions:
None.


xf_error_continue	( mess )


Description:
Continue reporting an error message after xf_error_start has been called.
Input:
STRING	mess	Additional line of error message to report.
Output:
None.
Error Conditions:
None.


xf_error_end	( )


Description:
End the reporting of an error message after xf_error_start has been called.
Input:
None.
Output:
None.
Error Conditions:
None.


xf_write_comment	( mess )


Description:
Write a comment to the history window/session file.
Input:
STRING	mess	Comment to write out.
Output:
None.
Error Conditions:
None.


xf_write_command	( mess )


Description:
Write a command to the history window/session file.
Input:
STRING	mess	Command to write out.
Output:
None.
Error Conditions:
None.


xf_write_query	( mess )


Description:
Write a query to the history window/session file.
Input:
STRING	mess	Query to write out.
Output:
None.
Error Conditions:
None.


xf_write_print	( mess )


Description:
Write a “print” message to the history window/session file.
Input:
STRING	mess	Message to write out.
Output:
None.
Error Conditions:
None.


xf_write_stdout	( mess )


Description:
Write a line to standard output, usually the terminal window.
Input:
STRING	mess	Line to write out.
Output:
None.
Error Conditions:
None.


xf_write_stderr	( mess )


Description:
Write a line to standard error, usually the terminal window.
Input:
STRING	mess	Line to write out.
Output:
None.
Error Conditions:
None.


xf_read_from_user	( inmess )


Description:
Read a response from the command line.
Input:
None.
Output:
STRING	inmess	Line entered by the user.
INTEGER	<Return Value>	Zero for success, else error message code.
Error Conditions:
None.


xf_read_stdin	( inmess )


Description:
Read a response from standard input (xterm window).
Input:
None.
Output:
STRING	inmess	Line read in from standard input.
INTEGER	<Return Value>	Zero for success, minus one for end of file, else error message code.
Error Conditions:
None.


write	( expr, ... )


io_write	( expr, ... )


ui_write	( expr, ... )


Description:
Write out a set of expressions, one per line, to the history window (or tty if no history window).
Input:
ANY	expr	General PCL expression to write out.
Output:
None.
Error Conditions:
None.


ui_read_logical	( prompt[, hotread] )


Description:
Display a form to the user requesting a yes/no response.
Input:
STRING	prompt	Prompt to display in the form.
LOGICAL	hotread	Optional and ignored.
Output:
LOGICAL	<Return Value>	True if YES button, False otherwise.
Error Conditions:
None.

Example:

ok = ui_read_logical( “Do you want to continue?” )


ui_read_integer	( prompt[, minval][, maxval] )


Description:
Display a form to the user requesting an integer response.
Input:
STRING	prompt	Prompt to display in the form.
INTEGER	minval	Optional lower bound for response.
INTEGER	maxval	Optional upper bound for response.
Output:
INTEGER	<Return Value>	Integer value that user entered or zero if aborted.
Error Conditions:
abort	Value returned is zero even if outside of range specified.

Example:

option = ui_read_integer( “1. Decrease, 2. Increase, 3. Quit”, 1, 3 )


ui_read_real	( prompt[, minval][, maxval] )


Description:
Display a form to the user requesting a real response.
Input:
STRING	prompt	Prompt to display in the form.
REAL	minval	Optional lower bound for response.
REAL	maxval	Optional upper bound for response.
Output:
REAL	<Return Value>	Value entered by user or zero for abort.
Error Conditions:
abort	Value returned is zero even if outside of range specified.

Example:

scale = ui_read_real( “Enter a scale factor for the operation” )


ui_read_string	( prompt[, option] )


Description:
Display a form to the user requesting a string response.
Input:
STRING	prompt	Prompt to display in the form.
INTEGER	option	Optional and ignored.
Output:
STRING	return	Value entered by user.
Error Conditions:
None.

Example:

username = ui_read_string( “What is your name?” )


ui_answer_message	( msgcode, answer )


Description:
Let PCL function supply answer to a user interface message prompt. The ui_answer_message call must occur BEFORE the user interface message appears.
Input:
INTEGER	msgcode	Integer code of message that response belongs to. This code is most easily found by first interactively generating the message and then looking in the resultant session file to see what code was generated. If -1 is used for the message code then the answer will apply to any message.
STRING	answer	Answer for the message. For normal user interface prompts, the valid strings are “YES”, “NO”, YESFOR ALL”, “NOFORALL”, and “ABORT”.
Output:
STRING	return	Value entered by user.
Error Conditions:
None.

Example:

/* Supply YES answer to next message no matter what it is
*/ui_answer_message( -1, “YES” )


ui_override_message	( msgcode, answer )


Description:
Let PCL function supply permanent answer to a user interface message prompt. The ui_override_message call must occur BEFORE the user interface message appears. The override stays in effect until it is cancelled with an empty answer string.
Input:
INTEGER	msgcode	Integer code of message that response belongs to. This code is most easily found by first interactively generating the message and then looking in the resultant session file to see what code was generated.
STRING	answer	Answer for the message. For normal user interface prompts, the valid strings are “YES”, “NO”, YESFOR ALL”, “NOFORALL”, and “ABORT”. An empty string, ““, is used to turn off the override.
Output:
STRING	return	Value entered by user.
Error Conditions:
None.

Example:

/* Supply YES answer always to the message:
* Do you wish to delete the original patches? */
ui_override_message( 1000030, “YES” )


write_line	( expr, ... )


io_write_line	( expr, ... )


ui_write_line	( expr, ... )


Description:
Write out a set of expressions trying to fit as much as possible into an 80 character output line, to the history window (or tty if no history window).
Input:
ANY	expr	General PCL expression to write out.
Output:
None.
Error Conditions:
None.


io_writec	( format, args... )


ui_writec	( format, args... )


Description:
Perform a limited C style format output to the history window. This routine is obsolete but exists for special purposes. Look at the TEXT_WRITE routine instead.
Input:
STRING	format	C Format string with handling of \n, \r, \t, %d, %f, %e, %g, %x, %s, %c, and %%.
unknown	args	Appropriate datatype for format specifiers. Incorrect specifications may cause a crash.
Output:
None.
Error Conditions:
None.


io_writef	( format, args... )


ui_writef	( format, args... )


Description:
Perform a limited FORTRAN style format output to the history window. This routine is obsolete but exists for special purposes. Look at the TEXT_WRITE routine instead.
Input:
STRING	format	FORTRAN format string with handling of /, 'string', X, I, F, E, G, and A formats.
unknown	args	Appropriate datatype for format specifiers. Incorrect specifications may cause a crash. Array arguments are allowed.
Output:
None.
Error Conditions:
None.

Message System Functions

The Patran messaging system allows PCL to access and display text strings. These text strings may be used for displaying messages or miscellaneous text (e.g. text strings that appear on forms - buttons, labels, etc.). Messages may either be written to the history window or displayed in a form which may require a user response (YES or NO). Additionally, messages may either be directly embedded in PCL or retrieved by a “message code”. Miscellaneous text is always retrieved by a message code.

The accessing routines fall into two categories; a simple interface that displays an embedded PCL message string in one of the message forms, and a rigorous interface that uses a numeric message code to retrieve general text strings and/or display a message in one of the message forms. This rigorous interface allows these strings to be customized by defining these strings in a user modifiable file.

For many customization activities, the simple interface (USER_MESSAGE) will be sufficient. In situations where text strings need to be externalized (defined outside of the code), the rigorous interface functions (MSG_xxx) must be used. These MSG_xxx functions (which are also used by Patran internally) allow for the retrieval and display of messages based on message codes (an integer). As these codes are also used during session file playback to validate message answers, they should be unique. MSC has reserved the values zero to 1 billion minus 1 (0 - 999,999,999) for internal use. While customers are free to use numbers beyond this range, PCL code should be written to allow these numbers to be changed in the case where multiple customizations will be combined that use the same set of numbers. For this reason, it is suggested that the C preprocessor be used extensively so that any required changes in numbering can be performed easily.

The MSG_xxx functions retrieve messages from either a primary or secondary file. The primary file (a read-only file that is delivered with Patran) is a specially processed file named “messages.database” that contains the text strings required by Patran. Any message code that is not in this primary file will be looked up in a secondary, user created message file. This file will be either the contents of the environment variable P3_USER_MESSAGES, or if not set, will be named user_messages.database and must exist on the PCL path. The format of the user message file requires each message code to begin in column 1 with the message text spanning as many lines as necessary. Blank lines and lines beginning with a # are ignored (to support the C preprocessor). A special symbol should be used as the base of a customization section to identify the application class.

Sample user_messages.database


<start of file>
1000000000	Some customization
#define form text labels
1000000001	Custom pick 1
1000000002	Custom string
#define messages
1000000100	An error was detected while attempting to perform a 143 type operation on %A%.\nDo you wish to continue?
<end of file>

This file assigns the application code (appcode) 1,000,000,000 to the application named “Some customization”. There are 2 form labels defined in this range (1,000,000,001 and 1,000,000,002), although the range of these numbers is completely unimportant as long as it is greater than one billion and unique. A single message numbered 1,000,000,100 is defined. It is a formatting string that requires a single string to be substituted in place of %A%. When this message is displayed, the first sentence will be terminated with a newline. Note the number 143 on the second message line. As long as a number does not appear in column 1, it is not considered a message number, and is therefore part of the message (number 1,000,000,100).

The routines USER_MESSAGE, MSG_TO_FORM and MSG_TO_TEXT require an argument (msgtype) that specifies the message severity. For USER_MESSAGE and MSG_TO_FORM, this value also controls the available buttons and determines the range of possible return values. Besides the ABORT button (which appears with all message forms), there are up to four (4) additional buttons that can appear with a CRITICAL or QUERY message and a selectable default value. The possible buttons are YES, NO, YES FOR ALL (YFA) and NO FOR ALL (NFA). The return message status code indicates how the user answered the question (for CRITICAL and QUERY messages).The possible return values are MSG_STAT_YES, MSG_STAT_NO, MSG_STAT_YESALL, MSG_STAT_NOALL, and MSG_STAT_ABORT. The following table lists these different combinations for both the simple and rigorous interfaces.


USER_MESSAGE	MSG_TO_FORM	description or
(msgtype - string)	(msgtype - integer)	available buttons
INFO	MSG_INFO	Informative message
WARN	MSG_WARNING	Warning message
ERROR	MSG_FATAL	Error/Fatal message
ACK	MSG_ACKNOWLEDGE	Acknowledgment message
x_YN	MSG_xxx_YN	YES, NO
x_YN_Y	MSG_xxx_YN_YDEFAULT	YES, NO, YES default
x_YN_N	MSG_xxx_YN_NDEFAULT	YES, NO, NO default
x_YNY	MSG_xxx_YNY	YES, NO, YES FOR ALL (YFA)
x_YNY_Y	MSG_xxx_YNY_YDEFAULT	YES, NO, YFA, YES default
x_YNY_N	MSG_xxx_YNY_NDEFAULT	YES, NO, YFA, NO default
x_YNYN	MSG_xxx_YNYN	YES, NO, YFA, NO FOR ALL (NFA)
x_YNYN_Y	MSG_xxx_YNYN_YDEFAULT	YES, NO, YFA, NFA, YES default
x_YNYN_N	MSG_xxx_YNYN_NDEFAULT	YES, NO, YFA, NFA, NO default
where:	x is either C (for CRITICAL) or Q (for QUERY).
	xxx is either CRITICAL or QUERY.
	See the include file pdamsg.h for constant values.

Sample usage:

status = MSG_TO_FORM(1000000100, MSG_CRITICAL_YN_NDEFAULT, 1000000000, 0, 0.0, “this entity”)

IF ( status == MSG_STAT_YES ) THEN

	<do something>

ENDIF


Important:	It is expected that all constants actually be define symbols that will be resolved by the C preprocessor.

In this example, the application code (1,000,000,000) will cause the string “Critical Decision requested from application Some customization” to be displayed as the header of the Patran modal message form. The form text box will contain the string:

“An error was detected while attempting to perform a 143 type operation on this entity.

Do you wish to continue?”

Additionally, the YES, NO and ABORT buttons will be available, with NO being the default button.

The MSG_TO_xxx functions will operate on a formatting string determined by the message code. This string will be retrieved from the primary or the secondary message file. See String I/O Conversion Utility Functions, 120 for detailed information about string formatting.


user_message	( type, appcode, appname, message )


Description:
Display a user message with the MSC.Patran user interface and possibly wait for and return a reply. The “type” determines whether the message is displayed in a form or simply output to the history window. The “type” also determines what buttons are available in the form. The “appcode” is a number assigned by the programmer which can be used in conjunction with ui_answer_message and ui_override_message to supply the message response during session file playback. Use of duplicate application codes will not generally cause problems but it is better if they are unique.
Input:
STRING	type[]	Type of message format desired. May be: “Info” Informative message “Warn” Warning message “Error” Error/Fatal message “Ack” Acknowledgment message “Q_YN” -Yes/No Query w/o default “Q_YN_Y” -Yes/No Query Yes default “Q_YN_N” -Yes/No Query No default “Q_YNY” -Yes/No/YesAll Query w/o default “Q_YNY_N” -Yes/No/YesAll Query No default “Q_YNYN” -Yes/No/YesAll/NoAll Query w/o default “Q_YNYN_Y” -Yes/No/YesAll/NoAll Query Yes default “Q_YNYN_N” -Yes/No/YesAll/NoAll Query No default “C_YN” -Yes/No Critical w/o default “C_YN_Y” -Yes/No Critical Yes default “C_YN_N” -Yes/No Critical No default “C_YNY” -Yes/No/YesAll Critical w/o default “C_YNY_N” -Yes/No/YesAll Critical No default “C_YNYN” -Yes/No/YesAll/NoAll Critical w/o default “C_YNYN_Y” -Yes/No/YesAll/NoAll Critical Yes default “C_YNYN_N” -Yes/No/YesAll/NoAll Critical No default
INTEGER	appcode	Application message code, unique value.
STRING	appname[]	Name of the application generating the message.
INTEGER	message[]	Message to display.
Output:
INTEGER	<Return Value>	1=Yes, 2=No, 3=Yes All, 4=Abort, 5=No All.

Example:

Please see user_message (p. 390) in the MSC Acumen Toolkit - Code Examples.


msg_get_string	( msgcode, string )


Description:
Retrieve a message string from the message file.
Input:
INTEGER	msgtype	Message code.
Output:
STRING	string	String retrieved from message file.
INTEGER	<Return Value>	Length of retrieved message string.
Error Conditions:
None.


msg_to_form	( msgcode, msgtype, appcode, ints, reals, chars )


Description:
Display a message in either a user interface form or in the history window.
Input:
INTEGER	msgcode	Message code to look up in message file.
INTEGER	msgtype	Message type value.
INTEGER	appcode	Application code reporting error. Use zero for general.
INTEGER()	ints	Integer data for message formatting.
REAL*()	reals	Real data for message formatting.
STRING[]()	chars	String data for message formatting.
Output:
INTEGER	<Return Value>	Message return code (MSG_STAT_YES, ...).
Error Conditions:
None.


msg_to_text	( msgcode, msgtype, appcode, ints, reals, chars, maxout, chan )


Description:
Write a message to a text I/O file.
Input:
INTEGER	msgcode	Message code to look up in message file.
INTEGER	msgtype	Message type value.
INTEGER	appcode	Application code reporting error.
INTEGER()	ints	Integer data for message formatting.
REAL*()	reals	Real data for message formatting.
STRING[]()	chars	String data for message formatting.
INTEGER	maxout	Maximum size of each output record.
INTEGER	chan	Channel from a text_open call or zero to write to standard output (xterm window).
Output:
INTEGER	<Return Value>	Should normally be 2.
Error Conditions:
None.

Event Manager

The “em_” routines interact with the user through the event manager, which allows the user to abort PCL programs and interact with the graphics systems similar to the way the delivered PCL performs.


em_proceed_normal	( )


Description:
This function returns FALSE if the user wants to abort and TRUE if the user does not want to abort. The user signals his abort request by clicking the Abort button and confirming the abort request on the Abort Confirmation form. This function also gives the system a chance to update the forms and the Patran viewports.
Input:
None.
Output:
LOGICAL	return	TRUE - Continue processing. FALSE - Abort processing.
Error Conditions:
None.


em_proceed_quick	( )


Description:
This function returns FALSE if the user wants to abort and TRUE if the user does not want to abort. This function is identical to em_proceed_normal except it does not allow the system to update the Patran viewports.
Input:
None.
Output:
LOGICAL	return	TRUE - Continue processing. FALSE - Abort processing.
Error Conditions:
None.


em_synchronize	( )


Description:
Synchronize events and graphics, making sure everything is up to date.
Input:
None.
Output:
None.
Error Conditions:
None.

Session File Functions

The following set of routines support session file recording and playback.


sf_record_default	( filename, rotations )


Description:
Define the default recording session file name. Typically, only the base name should be specified. The complete file name will be <basename>.ses.<version>. If an existing session file is specified, a higher version number will be automatically created. This command should only appear in the system startup file p3epilog.pcl.
Input:
STRING	filename	New name of recording session file.
LOGICAL	rotations	Write all rotation command to FILENAME.
Output:
None.
Error Conditions:
None.


sf_play_default	( filename, single_step )


Description:
Define the session file to be played after system initialization has completed. The complete filename <basename>.<extension>.<version> should always be used to eliminate any ambiguity that may arise from using the same recording and playing file basename.This command should only appear in the system startup file p3epilog.pcl.
Input:
STRING	filename	Name of session file to play.
LOGICAL	single_step	Play back the session file one line at a time.
Output:
None.
Error Conditions:
None.


sf_play	( filename )


Description:
Define a session file to be played. This command is typically used from inside a session file to play nested session files.
Input:
STRING	filename	Name of session file to play.
Output:
None.
Error Conditions:
None.


sf_commit	( commit_all )


Description:
Specify if each command played back from a session file should be committed to the database. This command is normally entered in the command line.
Input:
LOGICAL	commit_all	Commit every session file command.
Output:
None.
Error Conditions:
None.


sf_pause	( )


Description:
Allow the playing of a session file to be paused. This will stop/pause the current session file being played and bring up the form. This command is normally edited into a session file for future playback.
Input:
None.
Output:
None.
Error Conditions:
None.


sf_verbose	( write_sys_ms )


Description:
Define if system informational messages should be written to the recording session file.
Input:
LOGICAL	write_sys_msg	Write system messages to the session file
Output:
None.
Error Conditions:
None.


sf_write	( string )


Description:
Write a string to the recording session file. This command is not normally used.
Input:
STRING	string	String to write to the recording session file.
Output:
None.
Error Conditions:
None.


sf_write_disable	( status )


Description:
This function provides control over the mechanism used to write PCL function call information to session files.
Input:
LOGICAL	status	This value when set to TRUE will disable, and when set to FALSE will enable, the writing of PCL function call information to the session file.
Output:
None.
Error Conditions:
None.


sf_force_write	( string )


Description:
Write a string to the recording session file, even if recording is paused. This command is mainly used for debugging purposes.
Input:
STRING	string	String to write to the recording session file.
Output:
None.
Error Conditions:
None.


sf_rotation	( )


Description:
Define if the next command to be recorded is a rotation command. This will allow the rotation commands to be recorded only if the record rotations flag is TRUE. This command is normally used in compiled PCL.
Input:
None.
Output:
None.
Error Conditions:
None.

Example:

sf_rotation()

> gm_rot_x(value)

Obsolete File I/O Functions

The following set of I/O routines are still supported but are considered obsolete. See the File Utility Functions and Text File I/O Utility Functions for the new routines.


fio_openr	( filename, channel )


Description:
Open a text file for read only.
Input:
STRING	filename	File to open.
INTEGER	channel	Channel value to use for subsequent operations.
Output:
INTEGER	<Return Value>	Zero for success, otherwise error status.
Error Conditions:
None.


fio_openw	( filename, channel, overwrite )


Description:
Open a text file for write access.
Input:
STRING	filename	File to open.
FALSE	overwrite	Do not overwrite file if exists.
TRUE		Overwrite file if exists.
INTEGER	channel	Channel value to use for subsequent operations.
Output:
INTEGER	<Return Value>	Zero for success, otherwise error status.
Error Conditions:
None.


fio_opena	( filename, channel )


Description:
Open a text file for write access at end of file for appending.
Input:
STRING	filename	File to open.
INTEGER	channel	Channel value to use for subsequent operations.
Output:
INTEGER	<Return Value>	Zero for success, otherwise error status.
Error Conditions:
None.


fio_close	( channel )


Description:
Close a file opened with one of the FIO_OPENx routines.
Input:
INTEGER	channel	Channel value from the FIO_OPENx routine.
Output:
INTEGER	<Return Value>	Zero for success, otherwise error status.
Error Conditions:
None.


fio_delete	( filename )


Description:
Delete a file from the operating system.
Input:
STRING	filename	File to delete.
Output:
INTEGER	<Return Value>	Zero for success, otherwise error status.
Error Conditions:
None.


fio_rewind	( channel )


Description:
Set the file read/write position back to the start of the file.
Input:
INTEGER	channel	Channel value from the FIO_OPENx routine.
Output:
INTEGER	<Return Value>	Zero for success, otherwise error status.
Error Conditions:
None.


fio_read	( channel, string )


Description:
Read a string from a file.
Input:
INTEGER	channel	Channel value from the FIO_OPENx routine.
Output:
STRING	string	String read from the file. Must be at least two characters larger than the line being read.
INTEGER	<Return Value>	Zero for success, otherwise error status.
Error Conditions:
None.


fio_write	( channel, string )


Description:
Write a string to a file.
Input:
INTEGER	channel	Channel value from the FIO_OPENx routine.
STRING	string	String to write to the file.
Output:
INTEGER	<Return Value>	Zero for success, otherwise error status.
Error Conditions:
None.


fio_writec	( channel, format, args... )


Description:
Perform a limited C style format output to the file.
Input:
INTEGER	channel	Channel value from the FIO_OPENx routine.
STRING	format	C Format string with handling of \n, \r, \t, %d, %f, %e, %g, %x, %s, %c, and %%.
unknown	args	Appropriate datatype for format specifiers. Incorrect specifications may cause a crash.
Output:
None.
Error Conditions:
None.


fio_writef	( channel, format, args... )


Description:
Perform a limited FORTRAN style format output to the file.
Input:
INTEGER	channel	Channel value from the FIO_OPENx routine.
STRING	format	FORTRAN format string with handling of /, 'string', X, I, F, E, G, and A formats.
unknown	args	Appropriate datatype for format specifiers. Incorrect specifications may cause a crash. Array arguments are allowed.
Output:
None.
Error Conditions:
None.


fio_save_vars	( channel, var, var, ... )


Description:
Write out PCL variable definitions to a file.
Input:
INTEGER	channel	Channel value from the FIO_OPENx routine.
ANY	var	Variable definition to write out to file.
Output:
INTEGER	<Return Value>	Zero for success, otherwise error status.
Error Conditions:
None.