System Functions

PCL and Customization > System and Utility Functions > System Functions

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">

System Functions

System functions have varied functions and can be useful for getting system information or accessing special operations in the PCL environment


sys_move_raw	(source, destination)


Description:
Move raw data from one PCL variable to another. This function is not generally used but can occasionally be useful if data in one format needs to be accessed in another format.
Input:
ANY	source	The source variable to move information from.
Output:
ANY	destination	The destination variable to which to copy the source variable.
Error Conditions:
None.

Example:

REAL value = 3.14159

INTEGER bits

sys_move_raw( value, bits )

$ Bits is now the integer representation of the floating point number.

$ The value contained in bits will be completely machine dependent


sys_product	( )


Description:
Return a string representing the name of the product/application being executed.
Input:
None.
Output:
STRING	<Return Value>	Product name, such as “Patran”.
Error Conditions:
None.


sys_release	( )


Description:
Return a string representing the release/version of the product/application being executed.
Input:
None.
Output:
STRING	<Return Value>	Release/Version string.
Error Conditions:
None.


sys_date	( )


Description:
Return a string with the current date in dd-mm-yy format.
Input:
None.
Output:
STRING	<Return Value>	String representing date such as “25-Feb-92.”
Error Conditions:
None.


sys_time	( )


Description:
Return a string with the current time in hh:mm:ss format.
Input:
None.
Output:
STRING	<Return Value>	String representing time such as “12:52:22.”
Error Conditions:
None.


sys_clock	( )


Description:
Return the current time in seconds since midnight.
Input:
None.
Output:
REAL	<Return Value>	Current time in seconds since midnight expressed as a REAL.
Error Conditions:
None.


sys_cputime	( )


Description:
Return a cpu time value in seconds on a machine dependent base. It is recommended to use this value by taking the difference between two calls to the function in the same session. This routine returns the sum of the user and system time.
Input:
None.
Output:
REAL	<Return Value>	CPU time in seconds from unknown base.
Error Conditions:
None.


sys_allocate_array	(array, lb1, hb1 [, lb2, hb2 [, lb3, hb3 [, lb4, hb4 ]]] )


Description:
Allocate memory for a PCL virtual array variable. This function is more completely described in the virtual arrays section of the PCL manual
Input:
INTEGER	lb1	Lower bound for first dimension.
INTEGER	hb1	Higher bound for first dimension.
INTEGER	lb2	Optional lower bound for a second dimension.
INTEGER	hb2	Optional upper bound for a second dimension.
INTEGER	lb3	Optional lower bound for a third dimension.
INTEGER	hb3	Optional upper bound for a third dimension.
INTEGER	lb4	Optional lower bound for a fourth dimension.
INTEGER	hb4	Optional upper bound for a fourth dimension.
Output:
ANY(VIRTUAL)	array	Virtual array with storage allocated if available.
INTEGER	<Return Value>	Zero for success, else error code.
Error Conditions:
None.


sys_reallocate_array	(array, lb1, hb1 [, lb2, hb2 [, lb3, hb3 [, lb4, hb4 ]]] )


Description:
Re-allocate memory for a PCL virtual array variable. This function is more completely described in Virtual Arrays, 15.
Input:
ANY(VIRTUAL)	array	Original virtual array.
INTEGER	lb1	Lower bound for first dimension.
INTEGER	hb1	Higher bound for first dimension.
INTEGER	lb2	Optional lower bound for a second dimension.
INTEGER	hb2	Optional upper bound for a second dimension.
INTEGER	lb3	Optional lower bound for a third dimension.
INTEGER	hb3	Optional upper bound for a third dimension.
INTEGER	lb4	Optional lower bound for a fourth dimension.
INTEGER	hb4	Optional upper bound for a fourth dimension.
Output:
ANY(VIRTUAL)	array	Virtual array with storage reallocated if available.
INTEGER	<Return Value>	Zero for success, else error code.
Error Conditions:
None.

Remarks:

This function can only be used to increase the size of the array. An attempt to reduce the size of the array will not return an error value and will not reduce the size of the array.

This function will not reorder the data in original array. If a two-dimensional virtual array is reallocated so that the number of offsets in the second or column dimension are increased, the contents of the entries of the first or row dimension will be modified. See the example listed below.

Example:

FUNCTION reallocate_demonstration()

   INTEGER row_count

   INTEGER column_count

   INTEGER test_array(VIRTUAL)

   INTEGER row_size

   INTEGER column_size

   INTEGER return_value

   INTEGER array_value

/*

    * Set up the initial array sizes

*/

   column_size = 5

   row_size = 5

/*

    * Do the initial array allocation

*/

   return_value = sys_allocate_array ( test_array, 1, row_size, 1, column_size )

   IF (return_value != 0 ) THEN

      write(" ")

      write("Calling sys_allocate_array() has failed.")

      write(" ")

      dump return_value

   END IF

   write(" ")

   write("Initialize the array.")

   write(" ")

   array_value = 1

   FOR (row_count = 1 TO row_size)

      FOR (column_count = 1 TO column_size)

         test_array (row_count, column_count) = array_value

         array_value = array_value + 1

      END FOR

   END FOR

   dump test_array

   write(" ")

   write("Increase the row size.")

   write(" ")

   row_size = 10

   return_value = sys_reallocate_array ( test_array, 1, row_size, 1, column_size )

   IF (return_value != 0 ) THEN

      write(" ")

      write("Calling sys_allocate_array() has failed.")

      write(" ")

      dump return_value

   END IF

   dump test_array

   write(" ")

   write("Decrease the row size.")

   write(" ")

   column_size = 5

   row_size = 10

   return_value = sys_reallocate_array ( test_array, 1, row_size, 1, column_size )

   IF (return_value != 0 ) THEN

      write(" ")

      write("Calling sys_allocate_array() has failed.")

      write(" ")

      dump return_value

   END IF

   dump test_array

   write(" ")

   write("Deallocate, reallocate and reinitialize the original array.")

   write(" ")

   column_size = 5

   row_size = 5

   return_value = sys_free_array ( test_array )

   IF (return_value != 0 ) THEN

      write(" ")

      write("Calling sys_free_array() has failed.")

      write(" ")

      dump return_value

   END IF

   return_value = sys_allocate_array ( test_array, 1, row_size, 1, column_size )

   IF (return_value != 0 ) THEN

      write(" ")

      write("Calling sys_allocate_array() has failed.")

      write(" ")

      dump return_value

   END IF

   array_value = 1

   FOR (row_count = 1 TO row_size)

      FOR (column_count = 1 TO column_size)

         test_array (row_count, column_count) = array_value

         array_value = array_value + 1

      END FOR

   END FOR

   dump test_array

   write(" ")

   write("Increase the column size.")

   write(" ")

   column_size = 10

   return_value = sys_reallocate_array ( test_array, 1, row_size, 1, column_size )

   IF (return_value != 0 ) THEN

      write(" ")

      write("Calling sys_allocate_array() has failed.")

      write(" ")

      dump return_value

   END IF

   dump test_array

END FUNCTION

END FUNCTION


sys_free_array	( array )


Description:
Free memory for a PCL virtual array variable. This function is more completely described in Virtual Arrays, 15.
Input:
ANY(VIRTUAL)	array	Virtual array.
Output:
ANY(VIRTUAL)	array	Virtual array now deallocated
INTEGER	<Return Value>	Zero for success, else error code.
Error Conditions:
None.


sys_allocate_string	( string, size )


Description:
Allocate memory for a PCL virtual string variable. This function is more completely described in Virtual Arrays, 15.
Input:
INTEGER	size	New maximum size for the virtual string variable.
Output:
STRING	string	Virtual string with storage allocated if available.
INTEGER	<Return Value>	Zero for success, else error code.
Error Conditions:
None.


sys_reallocate_string	( string, size )


Description:
Re-allocate memory for a PCL virtual string variable. This function is more completely described in Virtual Arrays, 15.
Input:
STRING	string	Original virtual string.
INTEGER	size	New maximum size for the virtual string variable.
Output:
STRING	string	Virtual string with storage allocated if available.
INTEGER	<Return Value>	Zero for success, else error code.
Error Conditions:
None.


sys_free_string	( string )


Description:
Free memory for a PCL virtual array variable. This function is more completely described in Virtual Arrays, 15.
Input:
STRING	string	Virtual string.
Output:
STRING	string	Virtual string now deallocated.
INTEGER	<Return Value>	Zero for success, else error code.
Error Conditions:
None.


sys_array_hbound	( array, dim )


Description:
Return the upper bound for a dimension of an array.
Input:
ANY()	array	Array to return upper bound for.
INTEGER	dim	Dimension number to return bound for, one for first dimension.
Output:
INTEGER	<Return Value>	Upper bound of specified dimension of specified array.
Error Conditions:
None.


sys_array_lbound	( array, dim )


Description:
Return the lower bound for a dimension of an array.
Input:
ANY()	array	Array to return lower bound for.
INTEGER	dim	Dimension number to return bound for, one for first dimension.
Output:
INTEGER	<Return Value>	Lower bound of specified dimension of specified array.
Error Conditions:
None.


sys_array_nbound	( array )


Description:
Return the number of bounds/dimensions for an array.
Input:
ANY()	array	Array to return number of dimensions for.
Output:
INTEGER	<Return Value>	Number of dimensions of specified array or zero if not an array.
Error Conditions:
None.


sys_class_get	( classname, varname )


Description:
This function will return the value of a classwide variable from a class of PCL functions.
Input:
STRING	class_name[32]	This value specifies the name of the PCL function class from which the variable value will be retrieved.
STRING	variable_name[32]	This value specifies the name of the variable which will have its value retrieved.
Output:
DYNAMIC_ILRSW	<Return Value>	This function returns the value from the specified variable which is a member of the specified class.
Error Conditions:
None.

Remarks:

This function assumes that the caller already knows the data type of the variable whose contents will be returned.

Example:

None.


sys_class_set	( classname, varname, newvalue )


Description:
Set the contents of a class variable.
Input:
STRING	classname	Class name specified as a string.
STRING	varname	Variable name specified as a string.
UNKNOWN	newvalue	New value for the class variable. The value must be of the correct type.
Output:
None.
Error Conditions:
None.
Side Effects:
Unknown.	Be cautious with this routine. Most class functions do not expect their variables to change from accesses outside of the class definition.


sys_hash_stat	( tablename )


Description:
Output internal hash table statistics for various parts of the Patran system. This routine is primarily for performance tuning and is not expected to be used by the typical user.
Input:
STRING	tablename	Name of a system hash table.
Output:
STRING	tablename	Name of a system hash table.
LOGICAL	<Return Value>	True if hash table found, FALSE otherwise.
Error Conditions:
None.


sys_eval	(pcl_expression)


Description:
This function will execute a PCL expression contained in a string.
Input:
STRING	pcl_expression	This value provides the PCL expression that will be evaluated. This expression is evaluated in a global context where it will be assumed that any variables in the PCL expression will have a global scope. This global context prevents the use of any local variables in the PCL expression.
Output:
DYNAMIC_ILRS	<Return Value>	This function will return the results of the evaluated PCL expression. The type of the data returned will be defined by the evaluated PCL expression.
Error Conditions:
None.


sys_func_where	( func [, options] )


Description:
Search for type and existence of a PCL function.
Input:
STRING	func	Name of PCL function to search for.
INTEGER	options	Optional argument which if set to one causes a faster search to take place which might miss changes made to library lists.
Output:
INTEGER	<Return Value>	Result of check. If function does not exists, the value is zero. If the function is an intrinsic function, the value is one. If the function exists and is currently loaded into memory, the value is two. If the function exists, but is currently not in memory, the value is three.
Error Conditions:
None.


sys_sf_callopt	( options )


Description:
Set options for session file “>” processing lines. This routine is not normally expected to be used by users.
Input:
INTEGER	options	One to suppress all session, two to suppress next, zero to enable.
Output:
INTEGER	<Return Value>	Previous value of the options.
Error Conditions:
None.


sys_sf_argopt	( argnum, options )


Description:
Set options for session file “>” processing lines. This routine is not normally expected to be used by users.
Input:
INTEGER	argnum	Argument number to affect.
INTEGER	options	Sum of 1 for use variable instead of value, 2 for output declaration, and 4 for output class declaration.
Output:
INTEGER	<Return Value>	Previous value of the options.
Error Conditions:
None.


sys_sf_write	( string )


Description:
Write string to session file under control of SYS_SF_CALLOPT. This routine is not normally expected to be used by users.
Input:
STRING	string	String to write to the session file.
Output:
None.
Error Conditions:
None.


sys_sf_vwclear	( )


Description:
Clear variable written list. This routine is not normally expected to be used by users.
Input:
None.
Output:
None.
Error Conditions:
None.


sys_sf_commit	( )


Description:
Commit variable written list. This routine is not normally expected to be used by users.
Input:
None.
Output:
None.
Error Conditions:
None.


sys_sf_undo	( )


Description:
Undo variable written list up to last commit. This routine is not normally expected to be used by users.
Input:
None.
Output:
None.
Error Conditions:
None.


sys_poll_option	( option )


Description:
Set polling options for PCL compiler/interpreter for checking aborts, events, and graphics updates. This routine is not normally expected to be used by users but can speed up operations by minimizing graphics updates if used correctly.
Input:
INTEGER	option	Zero for full check, one for quick check, two for no check.
Output:
INTEGER	<Return Value>	Previous value of the options.
Error Conditions:
None.


sys_trace	( options )


Description:
Allow setting of tracing options during runtime execution. See !!TRACE (p. 9) for details.
Input:
STRING	options	String with any of blank separated keywords of “CALLS”, “LINES”, “EXITS”, “STDOUT”, “NOCALLS”, “NOLINES”, “NOEXITS”, “NOSTDOUT”, “NONE”.
Output:
STRING	<Return Value>	Previous value of the options.
Error Conditions:
None.


sys_traceback	( )


Description:;
Output a PCL error call traceback.
Input:
None.
Output:
None.
Error Conditions:
None.


sys_input	( filename [,noerror ] )


Description:
Allow setting of an input file during execution. See !!INPUT (p. 9) for details. Note: This routine will often work differently than expected as the inputted file is queued for execution and won't actually execute until PCL returns control to the user interface.
Input:
STRING	FILENAME	Name of operating system file to input.
LOGICAL	NOERROR	Optional flag which if set TRUE will suppress any error if the specified file does not exist.
Output:
LOGICAL	<Return Value>	True if input queued successfully.
Error Conditions:
None.


sys_stop_input	( )


Description:
Attempt to stop !!INPUT file during runtime execution.
Input:
None.
Output:
None.
Error Conditions:
None.


sys_library	( operation, args )


Description:
Allow setting of library options during runtime execution. See !!LIBRARY (p. 9) for details.
Input:
STRING	operation	String with operation keyword of either “”, “ADD”, “CREATE”, “DELETE”, “KEEPOPEN”, “LIST”, “MERGE”, “NONE”, “REHASH”, “REMOVE”, or “SORT”.
STRING	args	Filename(s) or function name(s) depending on operation specified.
Output:
None.
Error Conditions:
None.


sys_path	( operation, paths )


Description:
Allow setting of path options during runtime execution. See !!PATH (p. 9) for details.
Input:
STRING	operation	String with operation keyword of either “ ”, “NONE”, or “REMOVE”.
STRING	paths	Pathname(s) for operations.
Output:
None.
Error Conditions:
None.


sys_get_env	( ename, result )


Description:
Look up a system environment variablt name.
Input:
STRING	ename	Name of environment variable to look up. Note that this name is case sensitive on unix systems.
Output:
STRING	result	String result of environment definition if environment variable is defined.
INTEGER	<Return Value>	Zero for success, else error code if environment variable is not defined.
Error Conditions:
None.


sys_get_errno_msg	( enoval, result )


Description:
Translate a system “errno” value to a string.
Input:
INTEGER	enoval	System “errno” value.
Output:
STRING	result	String with message for specified errno.
Error Conditions:
None.


sys_get_info	( infotype, result )


Description:
Get various kind of “system” information.
Input:
INTEGER	infotype	Type of information desired, currently only 1=Machine Name.
Output:
STRING	result	Returned information as a string. For infotype=1, the possible returns are: SUNS, SGI5, RS6K, HP700, HPIPF, WINNT and LX86 with possible others in the future.
INTEGER	<Return Value>	Zero for success, else error.
Error Conditions:
None.


sys_get_user	( uname )


Description:
Get operating system user name for currently logged in user.
Input:
None.
Output:
STRING	uname	Login name of user logged in.
Error Conditions:
None.


utl_get_cust_info	( custnumber, custname )


Description:
Get customer information.
Input:
STRING	custnumber	Customer number string.
STRING	custname	Customer name string.
Output:
INTEGER	<Return Value>	Status, 0=success.
Error Conditions:
None.


utl_get_host_name	( host )


Description:
Retrieve name of operating system network host.
Input:
None.
Output:
STRING	host	Network host name.
Error Conditions:
None.


utl_get_product	( product )


Description:
Return Patran product name (same as sys_product).
Input:
None.
Output:
STRING	product	Product name string.
Error Conditions:
None.


utl_get_user_name	( user )


Description:
Retrieve name of operating system user.
Input:
None.
Output:
STRING	user	User name.
LOGICAL	<Return Value>	True for successful retrieval.
Error Conditions:
None.


utl_get_version	( version )


Description:
Return Patran version number (same as sys_release).
Input:
None.
Output:
STRING	version	Version number string.
Error Conditions:
None.


utl_process_spawn	( command, wait )


Description:
The program will execute a “fork” system call (or “vfork”, depending on the specific machine implementation) followed by an “execvp” system call with the “command” specified by the caller as its argument. The spawned command becomes a “process group leader.” This allows all processes created by this spawned process to be killed via the abort button or UTL_PROCESS_KILL. Redirection cannot be used in subprocess commands entered via utl_process_spawn. If redirection is required for the subprocess it is recommended that a bourne shell script be created which accepts the redirected input and output files as arguments and then issues the actual command of interest, including the redirection. This bourne shell script is what should be input to the utl_process_spawn function in this case.
Input:
STRING	command	Command string to execute.
LOGICAL	wait	True to wait for completion before continuing. False to execute command asynchronously.
Output:
INTEGER	<Return Value>	If WAIT is TRUE, then a return code is returned which needs to be checked by utl_process_error. If WAIT is FALSE, then the process group ID of the subprocess is returned. On Windows NT if WAIT is FALSE, then zero is returned.
Error Conditions:
None.

Example:

stat = utl_process_spawn( “lpr results.out”, TRUE )

IF( utl_process_error( stat ) ) THEN

   utl_display_process_error( stat, 3 )

END IF


Important:	The spawned process must not return the value 253. This value is reserved for MSC internal use.


utl_process_wait	( pid )


Description:
Wait for an asynchronous command to finish completion.
Input:
INTEGER	pid	Process ID returned from a previous call to utl_process_spawn with WAIT as FALSE.
Output:
INTEGER	<Return Value>	Status code that can be checked with utl_process_error.
Error Conditions:
None.


utl_display_process_error	( errcode, severity )


Description:
Display an error message based on a status code from one of the utl_process commands.
Input:
INTEGER	errcode	Status from utl_process_spawn or utl_process_wait.
INTEGER	severity	Type of form to use for display. 1=Info, 2=Warning, 3=Acknowlege, 4=Fatal.
Output:
None.
Error Conditions:
None.


utl_process_error	( errcode )


Description:
Check status of utl_process_spawn or utl_process_wait.
Input:
INTEGER	errcode	Status from utl_process_spawn or utl_process_wait.
Output:
LOGICAL	<Return Value>	TRUE if error occurred, FALSE otherwise.
Error Conditions:
None.


utl_process_kill	( pid )


Description:
To kill a spawned subprocess and all child processes created on its behalf.
Input:
INTEGER	pid	PID returned from UTL_PROCESS_SPAWN
Output:
None.
Error Conditions:
None.