PCL and Customization > User Interface and List Processor Functions > List Processor
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">   
List Processor
A set of PCL utilities are provided which parse Picklists. Picklists are the character strings which appear in selectdataboxes as a result of cursor selection or the user typing in data. Examples of these strings are:
point 1:8
solid 3.2
element 1:7:2
The system which supports the Picklist parsing is called the list processor. The list processor evaluates the strings listed above for information that the application can use. The PCL functions described in this section call the list processor. An include file is provided called lpenums.i (referenced by lpenums.p) on the delivery media which is helpful when writing PCL routines which call the list Processor. See The C Preprocessor, 31.
The PCL functions for parsing Picklists are grouped into two categories. The low-level, more flexible PCL functions which begin with the letters lp_ and the remaining routines which are a more “user friendly” interface to the same lp_ routines. Most list processor routines call the database to obtain information about the Picklist. Routines starting with fem_u_ are different in that they just evaluate for ids which don’t require querying the database. The result is improved performance. Note that not all the types of Picklist entities are supported by the higher level routines.
When the list processor evaluates a string such as the ones above, it returns to the user a handle, which points to the beginning of a list of items. Each item (or sublist) has a type, and attributes associated with that type. Some attributes such as label and id will be associated with most sublist types, and others such as the LP_ATTRIBUTE_COORDINATE_FRAME_TYPE attribute will only be associated with one particular item type (in this case a coordinate frame).
The list processor is also capable of evaluating strings such as “1:101:5.” In this case the list processor returns a handle which points at a list of tokens. In this case a token is merely a generic term for the integers (items) that the list contains.
File lpenums.i
The include file lpenums.i contains #define strings used by the list processor functions. The first section of lpenums.i contains encoded integer numbers used by lp_eval() to determine evaluation methods. The second section of lpenums.i contains sublist type filters used by the functions lp_sublist_type() and lp_sublist_count(). The third section of lpenums.i is used by lp_sublist_attribute_get_*() to parse for attributes contained within the sublist.
Evaluation Methods
There are currently eleven different evaluation methods. The different evaluation methods generate different types of lists. The LP_EVAL_PARSE_AND_EXPAND method prepares a list which can be parsed for the number, type and label of all entities in the list. Other evaluation methods can return more specific information such as the location of points or nodes.
 
Note:  
Some evaluation methods are for internal use only.
/* Evaluation methods for LpEval */ 
#define LP_EVAL_BARE_PARSE           							  1 (internal use only) 
#define LP_EVAL_PARSE_AND_EXPAND       							  2 (label only) 
#define LP_EVAL_FOR_TOKENS              							  3 (tokens only) 
#define LP_EVAL_FOR_ID                							  4 (label and id) 
#define LP_EVAL_FOR_LABEL              							  5 (label only) 
#define LP_EVAL_FOR_GEOMETRY             							  6 (geometric information) 
#define LP_EVAL_FOR_FEM_DEFINITION         							  7 (topology, node count, etc...) 
#define LP_EVAL_FOR_PICKLIST_ENUMERATION 							  8 (entity type ex.point, curve, node) 
#define LP_EVAL_FOR_PICKLIST_NORMALIZATION 9 (internal use only) 
#define LP_EVAL_FOR_PICKLIST_ADD        							  10 (internal use only) 
#define LP_EVAL_FOR_PICKLIST_DELETE        11 (internal use only) 
(Excerpt from lpenums.i)
Sublist Types and Filters
Depending on the Picklist, lp_eval() will prepare different types (sublists) of items. Each type will have different attributes. The SublistType filters are used by the PCL function lp_sublist_type() to verify the type of sublist referenced by the handle. Depending on how the picklist was parsed, each type of sublist will have different attributes associated with it. The filters are also used by lp_sublist_count() to count the number of entities of the specified type in the Picklist.
If a picklist has multiple points, lines and nodes, and the current application only needs to count the number of points and lines, use a geometry filter. Using only LP_SUBLIST_CURVE will count the number of lines whereas using LP_SUBLIST_GEOMETRY will count the number of lines and points and LP_SUBLIST_ANY will count the number of entities in the entire Picklist (points, lines and nodes). 
/* SublistType filters for LpSublistType */ 
#define LP_SUBLIST_POINT_IMMEDIATE                             1 
#define LP_SUBLIST_VECTOR_IMMEDIATE                            2 
#define LP_SUBLIST_POINT                                       4 
#define LP_SUBLIST_CURVE                                       8 
#define LP_SUBLIST_SURFACE                                    16 
#define LP_SUBLIST_SOLID                                      32 
#define LP_SUBLIST_GEOMETRY (LP_SUBLIST_POINT_IMMEDIATE    +   \
                             LP_SUBLIST_VECTOR_IMMEDIATE   +   \
                             LP_SUBLIST_POINT              +   \
                             LP_SUBLIST_CURVE              +   \
                             LP_SUBLIST_SURFACE            +   \
                             LP_SUBLIST_SOLID) 
#define LP_SUBLIST_COORD_FRAME                                64 
#define LP_SUBLIST_VECTOR                                    128 
#define LP_SUBLIST_AXIS                                      256 
#define LP_SUBLIST_NODE                                      512 
#define LP_SUBLIST_ELEMENT                                  1024 
#define LP_SUBLIST_MPC                                      2048 
#define LP_SUBLIST_FINITE_ELEMENT (LP_SUBLIST_NODE         +   \
                                   LP_SUBLIST_ELEMENT      +   \
                                   LP_SUBLIST_MPC) 
#define LP_SUBLIST_TOKEN_NULL                               4096  
#define LP_SUBLIST_TOKEN_INT                                8192 
#define LP_SUBLIST_TOKEN_FLOAT                             16384 
#define LP_SUBLIST_TOKEN_STRING                            32768 
#define LP_SUBLIST_TOKEN_FIELD                             65536 
#define LP_SUBLIST_TOKEN_MATERIAL                         131072 
#define LP_SUBLIST_TOKEN (LP_SUBLIST_TOKEN_NULL            +   \         
                          LP_SUBLIST_TOKEN_INT             +   \
                          LP_SUBLIST_TOKEN_FLOAT           +   \
                          LP_SUBLIST_TOKEN_STRING          +   \
                          LP_SUBLIST_TOKEN_FIELD           +   \
                          LP_SUBLIST_TOKEN_MATERIAL) 
#define LP_SUBLIST_ANY                                        
 
Sublist Attributes
Different Sublists have different attributes. Some sublists have no attributes while others can have many (more than 10). The number and type of attributes associated with each sublist depends on the method used for lp_eval() and the type of the sublist.
#define LP_ATTRIBUTE_ID								1 (internal id of entity)
#define LP_ATTRIBUTE_LABEL								2 (External visible label)
#define LP_ATTRIBUTE_GEOMETRY								3 (Coefficients)
#define LP_ATTRIBUTE_GEOMETRY_TYPE								4 (type code)
#define LP_ATTRIBUTE_GEOMETRY_FORMAT								5 (Format)
#define LP_ATTRIBUTE_GEOMETRY_COMPANY_OF_ORIGIN								6 (Company of origin)
#define LP_ATTRIBUTE_ORIGIN								7 (origin of coord frame)
#define LP_ATTRIBUTE_ROTATION_MATRIX								8 (rotation matrix)
#define LP_ATTRIBUTE_COORDINATE_FRAME_TYPE								9 (type code)
#define LP_ATTRIBUTE_LOCATION								10(nodal location)
#define LP_ATTRIBUTE_DISPLACEMENT								11(displacement)
#define LP_ATTRIBUTE_BASE								12(base of axis)
#define LP_ATTRIBUTE_TIP								13(tip of axis)?
#define LP_ATTRIBUTE_CLASS_NAME								14
#define LP_ATTRIBUTE_TOPOLOGY_ID								15(topology code)
#define LP_ATTRIBUTE_DIMENSIONALITY								16(dimensionality)
#define LP_ATTRIBUTE_FACE_NUMBER								17(face number)
#define LP_ATTRIBUTE_EDGE_NUMBER								18(edge number)
#define LP_ATTRIBUTE_VERTEX_NUMBER								19(vertex number)
#define LP_ATTRIBUTE_NODE_COUNT								20(number of nodes)
#define LP_ATTRIBUTE_NODE_LIST								21(list of node data)
#define LP_ATTRIBUTE_ORIGINAL_PARSE_CLASS								22(internal use only)
#define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS								23(internal use only)
#define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS_ID								24(internal use only)
#define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS_TOPOLOGICAL_CONTEXT		 25(internluseonly)
#define LP_ATTRIBUTE_GEOMETRY_IN_NATIVE_FORM								26(geometry data)
#define LP_ATTRIBUTE_TOKEN_VALUE								27(value of a token)
#define LP_ATTRIBUTE_EVALUATED_POINT								28
#define LP_ATTRIBUTE_POINT_COUNT								29
#define LP_ATTRIBUTE_CURVE_COUNT								30
#define LP_ATTRIBUTE_SURFACE_COUNT								31
#define LP_ATTRIBUTE_SOLID_COUNT								32
#define LP_ATTRIBUTE_POINT_LIST								33
#define LP_ATTRIBUTE_CURVE_LIST								34
#define LP_ATTRIBUTE_SURFACE_LIST								35
#define LP_ATTRIBUTE_SOLID_LIST								36
#define LP_ATTRIBUTE_SIDE_NUMBER								37
Example:
#include “lpenums.p”EXAMPLE 
INTEGER list_type = 0 
INTEGER handle, status, coord_label 
STRING list[VIRTUAL] 
WIDGET sdbox 
. 
. 
. 
ui_wid_get_vstring(sdbox, “VALUE”, list) 
status = lp_eval(list, LP_EVAL_FOR_LABEL, handle) 
IF (status != 0) THEN 
   RETURN status 
END IF 
WHILE(list_type != LP_SUBLIST_COORD_FRAME ) 
   status = lp_sublist_type(handle, LP_SUBLIST_ANY, list_type) 
   IF (status != 0) THEN 
      RETURN status 
   END IF 
/* now the list_type is LP_SUBLIST_COORD_FRAME */ 
END WHILE 
status = lp_sublist_attribute_get_int (handle, LP_ATTRIBUTE_LABEL, @
                                       coord_label) 
IF (status != 0) THEN 
   lp_eval_cleanup(handle) 
   RETURN status 
END IF
 
List Processor Functions
  
lp_eval
(list, method, handle )
Description:
 
 
Establish a new list processing anchor and handle.
Input:
 
 
STRING
list
Picklist from ui_wid_get_vstring on a select databox.
INTEGER
method
Code which indicates the evaluation method to use on the picklist. See lpenums.i
Output:
 
 
INTEGER
handle
Used by other lp utilities to parse the Picklist.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error
Error Conditions:
 
None.
 
 
Example:
 #include “lpenums.p” 
. 
. 
. 
status = lp_eval (coord, LP_EVAL_FOR_GEOMETRY, handle1) 
IF (status = 0) THEN 
   RETURN status 
END IF 
status = lp_sublist_attribute_get_int (handle1, LP_ATTRIBUTE_LABEL, @ 
                                       coord_label) 
IF (status = 0) THEN 
   lp_eval_cleanup(handle1) 
   RETURN status 
END IF 
 
List Processor Functions
  
lp_sub_str_by_keyword
(c_lp_str, c_keyword, case_sensitive, pvc_entity_ids )
Description:
 
 
Recover entity ids as they appear in the list processor string.
Input:
 
 
STRING[]
c_lp_str
Input string made with list processor
STRING[]
c_keyword
This value specifies the keyword for extracting entity ids. Ex: "Point", "Curve", "Surface", "Solid", "Node", "Element", "MPC" keyword_with_no_trailing_blank+" " will be used for the query.
INTEGER
case_sensitive
0 if FALSE
1 (or not 0) if TRUE
Output:
 
 
STRING[]
pvc_entity_ids
Pointer to address of virtural string containing all the entities ids as they appear in the list processor string. It will at least be allocated a minimum size of 1 char and set to ““ if a no error condition occured.
INTEGER
<Return Value>
This function returns a value of 0 when executed successfully.
Error Conditions:
 
None.
 
 
Remarks:
Memory is allocated for the virtual string pvc_entity_ids. Typically the deallocation would occur in the PCL program in which the virtual string was defined: string out[VIRTUAL]. Otherwise one must account for deallocation to avoid memory leaks.
List Processor Functions
  
lp_sublist_type
(handle, filter, type )
Description:
 
 
Indicates which type of sublist is referenced by the handle.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
INTEGER
filter
Filter from lpenums.i, it is most common to use LP_SUBLIST_ANY, or one of the more generic filters as this parameter.
Output:
 
 
INTEGER
type
Actual sublist type. See lpenums.i, sublist types.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
#include “lpenums.i”
INTEGER handle1,ent_type, count
INTEGER status
.
.
.
/* Now check to make sure that sublist type is a solid */
status = lp_sublist_type(handle1,LP_SUBLIST_ANY, ent_type)
IF ( ( status != 0 ) ||( ent_type != LP_SUBLIST_SOLID ) )THEN
	RETURN status
END IF
.
.
.
List Processor Functions
  
lp_sublist_count
(handle, filter, count )
Description:
 
 
Count the number of items in a sublist.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
INTEGER
filter
Filter from lpenums.i.
Output:
 
 
INTEGER
count
Number of items in sublist.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
#include “lpenums.p” 
. 
. 
. 
status = lp_eval(list_str, LP_EVAL_FOR_LABEL, handle) 
IF (status != 0) THEN 
   RETURN status 
END IF 
status = lp_sublist_count(handle, LP_SUBLIST_POINT, num_items) 
IF (status != 0) THEN 
   RETURN status 
END IF 
sys_allocate_array(point_labels, 1, num_items) 
i = 0 
REPEAT loop 
   status = lp_sublist_type(handle, LP_SUBLIST_ANY, list_type) 
   IF ( status != 0 ) THEN 
      RETURN status 
   ENDIF 
   IF ( list_type == LP_SUBLIST_POINT) THEN 
      status = lp_sublist_attribute_get_int(handle,LP_ATTRIBUTE_LABEL, @
                                            label) 
      IF (status == 0 ) THEN 
         i += 1 
         point_labels(i) = label 
      END IF 
      IF ( i == num_items ) THEN break loop 
   ENDIF 
   lp_sublist_next(handle) 
UNTIL ( i > num_items ) 
lp_eval_cleanup(handle) 
 
List Processor Functions
  
lp_sublist_next
(handle )
Description:
 
 
Set the list position to the next sublist.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
Output:
 
 
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
 FUNCTION list_get_id(handle1,ent_type,ent_list,count,ent_id)
/* Get the ids from a list of entities in a picklist */
 
#include “lpenums.i”
 
 INTEGER handle1,ent_type,ent_id(),count
 STRING ent_list[]
 
 INTEGER actual,icount,next_id(1),status
 LOGICAL end_of_list=False
 
 icount = 1
 WHILE (!end_of_list)
 
 	status = lp_sublist_type(handle1, ent_type, actual)
 	IF(status == 0) THEN
 		status = lp_sublist_attribute_get_int(handle1, LP_ATTRIBUTE_ID,@
 			next_id)
 		IF (status == 0) THEN
 			ent_id(icount) = next_id
 			icount += 1
 		END IF
 	END IF
 	status = lp_sublist_next(handle1)
 	IF (status != 0) THEN end_of_list = True
 	IF (icount > count) THEN BREAK
 
 END WHILE
 RETURN 0
END FUNCTION
List Processor Functions
  
lp_eval_cleanup
(handle )
Description:
 
 
Free allocated memory for list processor operations.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
Output:
 
 
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
 
Note:  
Must be called after all calls to parse a particular picklist.
Example:
 #include “lpenums.p”
.
.
.
status = lp_eval(coord, LP_EVAL_FOR_GEOMETRY, handle1)
 IF (status != 0) THEN
	RETURN status
 END IF
 status = lp_sublist_attribute_get_int @
	(handle1, LP_ATTRIBUTE_LABEL, @
	coord_label)
 IF (status != 0) THEN
	lp_eval_cleanup(handle1)
 RETURN status
 END IF
  
lp_sublist_attribute_get_int
(handle, attribute, item )
Description:
 
 
Return an array of integer values from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
INTEGER
attribute
Attribute requested from sublist. See lpenums.i.
Output:
 
 
INTEGER ARRAY
item
Item parsed from Picklist of the specified attribute.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
List Processor Functions
  
lp_sublist_attribute_get_float
(handle, attribute, item )
Description:
 
 
Return a real value of integer values from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
INTEGER
attribute
Attribute requested from sublist. See lpenums.i.
Output:
 
 
REAL
item
Item parsed from Picklist of the specified attribute.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
  #include “lpenums.p”
.
.
.
status = lp_eval(list_str, LP_EVAL_FOR_TOKENS, handle)
 IF (status != 0) THEN
 	RETURN status
 END IF
 
 status = lp_sublist_count(handle, LP_SUBLIST_TOKEN, ntokens)
 IF (status != 0) THEN
 	RETURN status
 END IF
 
 END IF
 IF (status!=0 || ntokens<=0) THEN
	 	lp_eval_cleanup(handle)
	RETURN status
 END IF
 status = SYS_ALLOCATE_ARRAY(rlist_vals, 1, ntokens)
IF (status==0) THEN
 	FOR (itoken = 1 TO ntokens)
 		IF (itoken>1) THEN status = lp_sublist_next(handle)
 		IF (status!=0) THEN BREAK
 		status = lp_sublist_attribute_get_float(handle, @
 			LP_ATTRIBUTE_TOKEN_VALUE, rlist_vals(itoken))
 		IF (status!=0) THEN BREAK
	END FOR
 END IF
List Processor Functions
  
lp_sublist_attribute_get_string
(handle, attribute, maxsize, item, size )
Description:
 
 
Return a string from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
INTEGER
attribute
Attribute requested from sublist. See lpenums.i.
INTEGER
maxsize
Size of output variable in bytes (use the following):
/* PCL interface help */
#define BYTES_PER_CHARACTER 1
Output:
 
 
STRING
item
Item parsed from Picklist of the specified attribute.
INTEGER
size
Actual return string size of item in bytes.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
  #include “lpenums.p”
.
.
.
status = lp_eval(show_entities, LP_EVAL_FOR_GEOMETRY, handle1)
 WHILE (status == 0)
 	/*
 	* Check Data, If good data, show it on spreadsheet widget
 	* (Dummy FOR structure allows breakout for errors)
 	*/
 	FOR(i = 1 TO 1)
 		/*
 		* Get id and label
 		*/
 		data_ck = lp_sublist_attribute_get_int @
 				(handle1, LP_ATTRIBUTE_ID, entity_id)
 		IF(data_ck != 0) THEN BREAK
 
 		/*
 		* Get geometry type
 		*/
 		data_ck = lp_sublist_attribute_get_string 				@
 				(handle1, 		@
 				LP_ATTRIBUTE_GEOMETRY_TYPE, 		@
 				BYTES_PER_CHARACTER * 64, 		@
 				type, size)
 		IF (data_ck != 0) THEN BREAK
 
 	END FOR
 	/*
 	* If error found while checking data, print error message
 	*/
 	IF (status != 0) THEN
 		RETURN data_ck
 	END IF
	/*
	 * Point to the next ID
	 */
 	status = lp_sublist_next(handle1)
 END WHILE
List Processor Functions
  
lp_sublist_attribute_get_inta
(handle, attribute, maxsize, item, size )
Description:
 
 
Return an array of integers from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
INTEGER
attribute
Attribute requested from sublist. See lpenums.i.
INTEGER
maxsize
Size of output variable in bytes (use the following):
/* PCL interface help */
#define BYTES_PER_INTEGER 4
Output:
 
 
INTEGER ARRAY
item()
Item parsed from Picklist of the specified attribute.
INTEGER
size
Actual array size returned in item in bytes.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
 #include “lpenums.p”
.
.
.
/* get node count*/
 IF (lp_sublist_attribute_get_int						@
 		(handle1,LP_ATTRIBUTE_NODE_COUNT,node_count) != 0) THEN
 	ui_writec(“Error in lp_sublist 2...”)
 	RETURN -3
 END IF
 
/* get nodes */
 sys_allocate_array(nodes,1,20)
 IF (lp_sublist_attribute_get_inta						@
 		(handle1,LP_ATTRIBUTE_NODE_LIST,node_count(1)*4,nodes,size) != 0) THEN
 	ui_writec(“Error in lp_sublist 3...”)
 	RETURN -3
 ELSE
 	FOR (count = 0 TO 19)
 		node_ids(start+count)=nodes(count+1)
 	END FOR
 	start+=20
 END IF
 sys_free_array(nodes)
List Processor Functions
  
lp_sublist_attribute_get_floata
(handle, attribute, maxsize, item_array, size )
Description:
 
 
Return a real array from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
INTEGER
attribute
Attribute requested from sublist. See lpenums.i.
INTEGER
maxsize
Size of output variable in bytes (use the following):
/* PCL interface help */
#define BYTES_PER_REAL 4
Output:
 
 
REAL ARRAY
item_array()
Item parsed from Picklist of the specified attribute.
INTEGER
size
The size of the item_array in bytes.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
 #include “lpenums.p”
.
.
.
 
status = lp_eval(coord, LP_EVAL_FOR_GEOMETRY, handle1)
 IF (status != 0) THEN
 	RETURN status
 END IF
 status = lp_sublist_attribute_get_floata @
 	(handle1, LP_ATTRIBUTE_ROTATION_MATRIX, @
 	BYTES_PER_REAL * 9, @
 	rmatrix, size)
 IF (status != 0) THEN
 	lp_eval_cleanup(handle1)
 	RETURN status
 END IF
END IF
List Processor Functions
  
lp_print_list
(handle )
Description:
 
 
Print the entire Picklist from the anchor block to standard out (The invoking xterm).
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
Output:
 
 
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
 #include “lpenums.p”
.
.
.
 
status = lp_eval(coord, LP_EVAL_FOR_GEOMETRY, handle1)
lp_print_list(handle1)
 IF (status != 0) THEN
 	RETURN status
 END IF
 status = lp_sublist_attribute_get_int @
 	(handle1, LP_ATTRIBUTE_LABEL, @
 	coord_label)
 IF (status != 0) THEN
 	lp_eval_cleanup(handle1)
 	RETURN status
 END IF
  
lp_print_sublist
(handle )
Description:
 
 
Print the sublist prepared by lp_sublist_type from the anchor block to standard out (The invoking xterm).
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
Output:
 
 
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
List Processor Functions
  
lp_sublist_reset
(handle )
Description:
 
 
Reset the sublist parser to resume parsing the original Picklist.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
Output:
 
 
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
  #include “lpenums.p”
.
.
.
 status = lp_eval(ent_list,LP_EVAL_FOR_ID,handle1)
 IF (status != 0) THEN RETURN status
 IF (!em_proceed_quick()) THEN RETURN 0
 db_count_curve(nbrae)
 IF(nbrae == 0) THEN
	lp_eval_cleanup(handle1)
 	RETURN 48000006
 END IF
 SYS_ALLOCATE_ARRAY(eids,1,nbrae)
 FOR (iall = 1 to 4) ialloop
 	Switch (iall)
 		CASE (1)
 			ent_type = LP_SUBLIST_POINT
 		CASE (2)
 			ent_type = LP_SUBLIST_CURVE
 		CASE (3)
 			ent_type = LP_SUBLIST_SURFACE
 		CASE (4)
 			ent_type = LP_SUBLIST_SOLID
 		DEFAULT
 			RETURN
 		END SWITCH
 
 	status = lp_sublist_reset(handle1)
 	status = lp_sublist_count(handle1,ent_type,lid)
 	IF (status != 0) THEN
 		lp_eval_cleanup(handle1)
 		RETURN status
 	END IF
	FOR (i = 1 To lid) Doloop
.
.
.
	END FOR
END FOR
List Processor Functions
  
lp_sublist_fetch
(handle, maxsize, item, size )
Description:
 
 
Return the contents of a sublist.
Input:
 
 
INTEGER
handle
Returned by call to lp_eval().
INTEGER
maxsize
Size in bytes of “item”.
Output:
 
 
STRING
item
Contents of sublist.
INTEGER
size
Actual size returned.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
List Processor Functions
  
lp_keyword_text
(keyword, family, text )
Description:
 
 
The purpose of this function is to return the keywords found in Patran that are used to describe objects, actions, etc.
NOTE: This function receives parameters in a nonintuitive fashion. The family is the first method of grouping, and the keyword is next. 1,3 yields point, and 2,3 yields grid. This should show that they keywords are organized by family, the second parameter. Below is shown all the families, and then a listing of the LpGEOMETRY family.
Input:
 
 
INTEGER
keyword
Identifies the entity. From lpkeywords.i:
(SAMPLE for family LpGEOMETRY)
#define LpPOINT 1
#define LpGRID 2
#define LpCURVE 3
#define LpLINE 4
#define LpSURFACE 5
#define LpPATCH 6
#define LpSOLID 7
#define LpHYPERPATCH 8
#define LpPOINT_IMMEDIATE 9
#define LpSCREEN_PICK 10
#define LpCOORDINATE_FRAME 11
#define LpVECTOR 12
#define LpAXIS 13
#define LpVECTOR_IMMEDIATE 14
#define LpAXIS_IMMEDIATE 15
#define LpSIDE_NUMBER 16
INTEGER
family
Identifies the group of entities keyword falls. From lpkeywords.i:
/* listing of possible families */
#define LpACTION 1
#define LpTECHNIQUE 2
#define LpGEOMETRY 3
#define LpFINITE_ELEMENT 4
#define LpDESIGNATOR 5
#define LpATTRIBUTE 6
#define LpGEOMETRY_TYPES 7
#define LpGEOMETRY_FORMATS 8
#define LpGEOMETRY_COOS 9
#define LpOPERATION 10
#define LpTOKEN_TYPES 11
#define LpELEMENT_TYPES 12
#define LpNUMERIC_STANDIN 13
Output:
 
 
STRING[32]
item
String alias for keyword.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
  #include “lpenums.p”
.
.
.
/*$$ FUNCTION refresh
 *
 * Purpose:
 * Update the Reference Coordinate Frame if the preference has been
 * changed.
 *
*/
 FUNCTION refresh
 	STRING default_cid[NAME_LENGTH]
 	STRING coord_frame_id[NAME_LENGTH]
 
 	INTEGER status
 
 	/*
	 * Get the Preference Default Coordinate Frame
	 */
	 default_cid = uil_group_transform.pref_cid()
 
	/*
	 * Get the List Processor’s nomenclature for Coordinate Frame
	 */
 	status = lp_keyword_text(LpCOORDINATE_FRAME, LpGEOMETRY, coord_frame_id)
	IF (status != 0) THEN RETURN status
 
 	/*
	 * Add the Id ...
	 */
	 coord_frame_id = coord_frame_id// “ “ // default_cid
 
 
 	/*
	 * ... and set the selectdatabox
	 */
	 ui_wid_set(coord_dbox, “VALUE”, coord_frame_id)
 
 END FUNCTION /* refresh */
List Processor Functions
  
lp_picklist_string_creator_v
(items, item_count, sort, vstring )
Description:
 
 
Create a valid Picklist in a virtual string from an array of ids.
Input:
 
 
INTEGER(item_count,6)
items
Each row consists of the following:
items(,1): entity Class (i.e. LpGEOMETRY)
items(,2): entity Type (i.e. LpSOLID)
items(,3): entity Identifier (i.e. 28, for label 28)
items(,4): entity SubIdentifier1 (i.e. 2, for solid 28; 0=N/A) face 2 of solid 28
items(,5): entitySubIdentifier2 (i.e. 1, for edge 1of surface 2 of solid 28; 0=N/A) edge 1 of surface 2 of solid 28
items(,6): entitySubIdentifier3 (i.e. 2, for vertex 2 of edge 1 of surface 2 of solid 28; 0=N/A) vertex 2 of edge 1 of surface 2 of solid 28
INTEGER
item_count
Number of items.
INTEGER
sort
If non zero, sort the items in ascending order, otherwise keep in original (Input) order.
Output:
 
 
STRING
[VIRTUAL] vstr
PCL virtual string to receive character list.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
  #include “lpenums.p”
 CLASSWIDE WIDGET node_id 
 STRING node_list[VIRTUAL]
INTEGER status, nodes(VIRTUAL), pklist(VIRTUAL), nnodes
.
.
.
 /*
 * Get the nodes from the node selectdatabox.
 */
 ui_wid_get_vstring(node_id, “VALUE”, node_list)
 /*
 * Count the number of nodes in the node list.
 */
 nnodes = app_count_id_list(LP_SUBLIST_NODE, node_list, @
 				FALSE, status)
IF (status != 0) THEN RETURN status
/*
 * Allocate a virtual array to store the node ids.
List Processor Functions
*/
 status = SYS_ALLOCATE_ARRAY(nodes, 1, nnodes)
 IF(status != 0) THEN RETURN 1
/*
 * Allocate a virtual array to store the pick list information.
 */
 status = SYS_ALLOCATE_ARRAY(pklist, 1, nnodes, 1, 6)
 IF(status != 0) THEN RETURN 1
/*
 * Extract the node IDs from the selectdatabox string.
 */
 status = fem_u_extract_node_ids(node_list, nnodes, nodes(1:))
 IF(status != 0) THEN RETURN 1
/*
 * Set the picklist array.
 */
 FOR(i = 1 TO nnodes)
 	pklist(i,1) = LpFINITE_ELEMENT
 	pklist(i,2) = LpNODE
 	pklist(i,3) = nodes(i)
 	pklist(i,4) = 0
 	pklist(i,5) = 0
 	pklist(i,6) = 0
 END FOR
 /*
 * Build a node list string from the node array.
 */
 status = lp_picklist_string_creator_v(pklist(1:,1:), nnodes, @
 				0, node_list)
 IF(status != 0) THEN RETURN 1
  
app_count_id_list
(filter, lst, domesg, status )
Description:
 
 
Count the entities of a specified list processor type in a list using the picklist decoder routines.
Input:
 
 
INTEGER
filter
Filter from lpenums.i.
STRING
lst
Picklist from a selectdatabox.
LOGICAL
domesg
If TRUE, issue a message if error condition occurs.
Output:
 
 
INTEGER
status
Message facility code. See Message System Functions, 155. 0 indicates no error.
INTEGER
<Return Value>
Number of entities in the picklist of the specified type.
Error Conditions:
 
None.
 
 
List Processor Functions
  
app_count_token_list
(lst, domesg, status )
Description:
 
 
Count the number of tokens that are contained in a Picklist.
Input:
 
 
STRING
lst
Picklist from a selectdatabox.
LOGICAL
domesg
If TRUE, issue a message if error condition occurs.
Output:
 
 
INTEGER
status
Message facility code. See Message System Functions, 155. 0 indicates no error.
INTEGER
<Return Value>
Number of tokens in the picklist.
Error Conditions:
 
None.
 
 
  
app_get_handle
(lst, method, domesg, handle )
Description:
 
 
Open a list for processing.
Input:
 
 
STRING
lst
Picklist from a selectdatabox.
INTEGER
method
Evaluation method from lpenums.i.
LOGICAL
domesg
If TRUE, issue a message if error condition occurs.
Output:
 
 
INTEGER
handle
List pointer.
INTEGER
<Return Value>
Number of tokens in the picklist.
Error Conditions:
 
None.
 
 
List Processor Functions
  
app_next_id
(handle,filter, lst, domesg, eol, status )
Description:
 
 
Get the next id for a sublist (item) from a previously generated list.
Input:
 
 
INTEGER
handle
List pointer returned from app_get_handle.
INTEGER
filter
Filter from lpenums.i.
STRING
lst
Picklist from a selectdatabox.
LOGICAL
domesg
If TRUE, issue a message if error condition occurs.
LOGICAL
eol
Set to FALSE before making call. Returns TRUE when end of file encountered.
Output:
 
 
LOGICAL
eol
Returned as TRUE when end of file encountered.
INTEGER
status
Message facility error.
INTEGER
<Return Value>
ID of next item in Picklist.
Error Conditions:
 
None.
 
 
  
app_next_label
(handle, filter, lst, domesg, eol, status )
Description:
 
 
Get the next label for a sublist item from a previously generated list.
Input:
 
 
INTEGER
handle
List pointer returned from app_get_handle.
INTEGER
filter
Filter from lpenums.i.
STRING
lst
Picklist from a selectdatabox.
LOGICAL
domesg
If TRUE, issue a message if error condition occurs.
LOGICAL
eol
Set to FALSE before making call. Returns TRUE when end of file encountered.
Output:
 
 
LOGICAL
eol
Returned as TRUE when end of file encountered.
INTEGER
status
Message facility error.
INTEGER
<Return Value>
Label of next item in Picklist.
Error Conditions:
 
None.
 
 
List Processor Functions
  
app_lp_err_msg
(domesg, lst, lp_routine, caller, status )
Description:
 
 
Handle a list processor error.
Input:
 
 
LOGICAL
domesg
If TRUE, issue a message if error condition occurs.
STRING
lst
Picklist from a selectdatabox.
STRING
lp_routine
Name of the list processor routine that detected the error.
STRING
caller
Name of the routine that called the list processor routine.
INTEGER
status
List processor status code.
Output:
 
 
None.
 
 
Error Conditions:
 
None.
 
 
Side Effects:
• If DOMESG is true, a fatal error message will be written.If a database error, the following message will be written:
Database error during List Processing: [DB error message]
• If a list processor error, the following message will be written:
Unable to process list: “[contents of LIST]”
List Processor Functions
  
fem_u_count_id_list
(sublist_type, lst, domesg, status )
Description:
 
 
Count the entities of a specified list processor sublist type in a list using the picklist decoder routines.
Input:
 
 
INTEGER
sublist_type
Works only with following types from lpenums.p As follows:
LP_SUBLIST_FINITE_ELEMENT
LP_SUBLIST_NODE
LP_SUBLIST_ELEMENT
LP_SUBLIST_MPC
LP_SUBLIST_GEOMETRY
LP_SUBLIST_POINT
LP_SUBLIST_CURVE
LP_SUBLIST_SURFACE
LP_SUBLIST_SOLID
LP_SUBLIST_ANY
STRING
lst
Picklist from a selectdatabox.
LOGICAL
domesg
If TRUE, issue a message if error condition occurs.
Output:
 
 
INTEGER
status
Message facility code. See Message System Functions, 155. 0 indicates no error.
INTEGER
<Return Value>
Number of entities in the picklist of the specified type.
Error Conditions:
 
None.
 
 
 
Note:  
This does not work for all sub-list types. Use lp_sublist_count if the particular type of interest is not included here. In general, this routine performs better (Take less time) than lp_sublist_count.
Example:
#include “lpenums.i”
 STRING ent_list[]
 INTEGER status
 INTEGER lid
lid = fem_u_count_id_list(LP_SUBLIST_ELEMENT,ent_list,FALSE,status)
 IF ( status != 0 ) THEN
 	RETURN status
 END IF
 IF (lid == 0) THEN
	RETURN 48000004
 END IF
List Processor Functions
  
fem_u_extract_node_ids
(node_list, num_nodes, id_nodes )
Description:
 
 
Extract the array of nodes IDs from a Picklist.
Input:
 
 
STRING
node_list
Picklist string.
INTEGER
num_nodes
Number of nodes, from fem_u_count_id_list() normally.
Output:
 
 
INTEGER(num_nodes)
id_nodes
Array of node IDs.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
Example:
CLASSWIDE WIDGET node_id 
 STRING node_list[VIRTUAL]
INTEGER status, nodes(VIRTUAL), nnodes
.
.
.
 /*
 * Get the nodes from the node selectdatabox.
 */
 ui_wid_get_vstring(node_id, “VALUE”, node_list)
 /*
 * Count the number of nodes in the node list.
 */
 nnodes = app_count_id_list(LP_SUBLIST_NODE, node_list, @
 				FALSE, status)
IF (status != 0) THEN RETURN status
/*
 * Allocate a virtual array to store the node ids.
 */
 status = SYS_ALLOCATE_ARRAY(nodes, 1, nnodes)
 IF(status != 0) THEN RETURN 1
/*
 * Allocate a virtual array to store the pick list information.
 */
 status = SYS_ALLOCATE_ARRAY(pklist, 1, nnodes, 1, 6)
 IF(status != 0) THEN RETURN 1
/*
 * Extract the node IDs from the selectdatabox string.
 */
 status = fem_u_extract_node_ids(node_list, nnodes, nodes(1:))
 IF(status != 0) THEN RETURN 1
List Processor Functions
  
fem_u_get_free_faces
(el_ids, max_nodes, max_per_face, max_faces, nels, el_con, el_shape, el_nodes, face_el_ids, face_ids, free_faces)
Description:
 
 
Create a list of all free element faces in a list of solid finite elements.
Input:
 
 
INTEGER
el_ids()
List of solid elements.
INTEGER
max_nodes
Maximum number of nodes per element in EL_IDS.
INTEGER
max_per_face
Maximum number of nodes per face in EL_IDS.
INTEGER
max_faces
Maximum number of faces for any element in EL_IDS.
INTEGER
nels
Number of elements.
INTEGER
el_con()
Element node list (Connectivity).
INTEGER
el_shape()
Element shape array.
INTEGER
el_nodes()
Element node count array.
Output:
 
 
INTEGER
face_el_ids()
Associated element ID.
INTEGER
face_ids()
Free face ID.
INTEGER
free_faces
Number of free faces.
INTEGER
<Return Value>
0, no error.
1, Unsupported element type (shape/nodes).
2, Memory allocation error.
Error Conditions:
 
None.
 
 
Example:
*/
   INTEGER elem_topo_codes(VIRTUAL)
   INTEGER shape_code(VIRTUAL)
   INTEGER nodes_per_elem(VIRTUAL)
   INTEGER connectivity(VIRTUAL)
   INTEGER face_elem_ids(VIRTUAL)
   INTEGER keep_face_elem_ids(VIRTUAL)
   INTEGER free_elements(VIRTUAL)
   INTEGER face_ids(VIRTUAL)
   INTEGER elem_ids(VIRTUAL)
   INTEGER status
   INTEGER cntr1
   INTEGER num_elems
   INTEGER num_free_faces
   INTEGER group_id
/*
 *.. Now allocate element and node arrays ...
 */
   status = db_get_current_group_id( group_id )
   IF( status != 0 ) THEN RETURN status
   status = db_count_elems_in_group( group_id, num_elems )
   IF( status != 0 ) THEN RETURN status
   status = sys_allocate_array( elem_ids, 1, num_elems )
   IF( status != 0 ) THEN RETURN status
/*
 * fetch all the element ids ...
 */
   status = db_get_elem_ids_in_group( num_elems, group_id, elem_ids )
   IF( status != 0 ) THEN RETURN status
   IF ( num_elems <= 0 ) THEN RETURN
   status = sys_allocate_array( elem_topo_codes, 1, num_elems )
   IF( status != 0 ) THEN RETURN status
   status = sys_allocate_array( shape_code, 1, num_elems )
   IF( status != 0 ) THEN RETURN status
   status = sys_allocate_array( nodes_per_elem, 1, num_elems )
   IF( status != 0 ) THEN RETURN status
   status = sys_allocate_array( connectivity , 1,8*num_elems )
   IF( status != 0 ) THEN RETURN status
   status = sys_allocate_array( face_elem_ids, 1,6*num_elems)
   IF( status != 0 ) THEN RETURN status
   status = sys_allocate_array( keep_face_elem_ids, 1,6*num_elems)
   IF( status != 0 ) THEN RETURN status
   status = sys_allocate_array( free_elements, 1,6*num_elems)
   IF( status != 0 ) THEN RETURN status
   status = sys_allocate_array( face_ids, 1,6*num_elems)
   IF( status != 0 ) THEN RETURN status
/*
 * .. Get the associated nodes ...
 */
   status = db_get_nodes_for_elems( num_elems, 8, elem_ids, connectivity )
   IF( status != 0 ) THEN RETURN status
   status = db_get_elem_etop( num_elems, elem_ids, elem_topo_codes )
   IF( status != 0 ) THEN RETURN status
   status = db_get_elem_topology_data( num_elems, elem_topo_codes, @
                                       shape_code, nodes_per_elem)
   IF( status != 0 ) THEN RETURN status
    /* set up array for later referencing to tell if element is a wedge 
      or a hex */
   status = db_get_nodes_for_elems( num_elems, 8, elem_ids, connectivity )
   IF( status != 0 ) THEN RETURN status
   status = fem_u_get_free_faces( elem_ids, 8, 4, 6, num_elems, connectivity ,@
                                  shape_code, nodes_per_elem, @
                                  face_elem_ids, face_ids, num_free_faces )
   IF( status != 0 ) THEN RETURN status
   DUMP num_free_faces, face_elem_ids(1:num_free_faces)
   RETURN 0
END FUNCTION
  
fem_u_get_id_list
(sublist_type, lst, nument, domesg, ids )
Description:
 
 
Return the entities ids of a specified list processor sublist type in a list using the picklist decoder routines.
Input:
 
 
INTEGER
sublist_type
Works only with following types from lpenums.p As follows:
LP_SUBLIST_FINITE_ELEMENT
LP_SUBLIST_NODE
LP_SUBLIST_ELEMENT
LP_SUBLIST_MPC
LP_SUBLIST_GEOMETRY
LP_SUBLIST_POINT
LP_SUBLIST_CURVE
LP_SUBLIST_SURFACE
LP_SUBLIST_SOLID
LP_SUBLIST_ANY
STRING
lst
Picklist from a selectdatabox.
INTEGER
nument
Number of entities to get.
LOGICAL
domesg
If TRUE, issue a message if error condition occurs.
Output:
 
 
INTEGER(nument)
ids
Array of entity ids.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
 
Note:  
fem_u_get_id_list does not work for all sub-list types. Use lp_sublist_type and lp_sublist_next if the particular type of interest is not included here. In general, this routine performs better (takes less time) than lp_sublist_type and lp_sublist_next.
Example:
#include “lpenums.p”
 STRING list1_entities[VIRTUAL]
 INTEGER node_ids1(VIRTUAL), num_nodes1
.
.
.
/*
 * Count the nodes in the list and return if there are no nodes or we
 * can’t process the list
 */
 
 num_nodes1 = fem_u_count_id_list(LP_SUBLIST_NODE, list1_entities, @
 					true, status)
 IF(num_nodes1 <= 0 || status != 0) THEN RETURN
 
/*
 * Get the IDs of the nodes
 */
 
 IF(sys_allocate_array(node_ids1, 1, num_nodes1) != 0) THEN RETURN
 status = fem_u_get_id_list(LP_SUBLIST_NODE, list1_entities, @
 				num_nodes1, true, node_ids1)
  
fem_u_get_subid_list
(sublist_type, lst, nument, domesg, ids, fids, edids )
Description:
 
 
Return the entities face ids and edges ids of a specified list processor sublist type in a list using the picklist decoder routines.
Input:
 
 
INTEGER
sublist_type
Works only with following types from lpenums.p As follows:
LP_SUBLIST_FINITE_ELEMENT
LP_SUBLIST_NODE
LP_SUBLIST_ELEMENT
LP_SUBLIST_MPC
LP_SUBLIST_GEOMETRY
LP_SUBLIST_POINT
LP_SUBLIST_CURVE
LP_SUBLIST_SURFACE
LP_SUBLIST_SOLID
LP_SUBLIST_ANY
STRING
lst
Picklist from a selectdatabox.
INTEGER
nument
Number of entities to get.
LOGICAL
domesg
If TRUE, issue a message if error condition occurs.
Output:
 
 
INTEGER(nument)
ids
Array of entity ids.
INTEGER(nument)
fids
Face ids of the entities.
INTEGER(nument)
edids
Edge ids of the entities.
INTEGER
<Return Value>
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions:
 
None.
 
 
 
Note:  
fem_u_get_subid_list does not work for all sub-list types. Use lp_sublist_type and lp_sublist_next if the particular type of interest is not included here. In general, this routine performs better (takes less time) than lp_sublist_type and lp_sublist_next.
Example: Creating a Simple Customized Menu and Form
Many times it is desired to create an additional menu that is to appear on the Main Menubar. User created menus will appear between the Applications menu and the Help menu. Customized forms may be displayed as the result of a menu selection from a customized menu item or as the result of clicking on a customized button. In either case, the PCL is exactly the same to define the form and its widgets. The following example provides the necessary PCL to create a customized menu and form. Although the example is quite simple, the basic ideas are presented. More complex examples are provided later in this book.
The p3epilog.pcl file is used to link customized PCL to Patran. Refer to The p3prolog.pcl and p3epilog.pcl Files (p. 54) in the Patran Reference Manual for more information concerning this file. Often times it is useful to refer to the PCL file or compiled PCL and, if necessary, initialize the functionality from the p3epilog.pcl file. For example, to reference the PCL in the following example which creates a customized menu and form, the required p3epilog.pcl file would be:
/*
 * Add the PCL to the existing set of libraries accessed by Patran.
 */
!! INPUT your_custom.pcl
 
/*
 * Run the init function of the user_pcl class to create the menu and
 * the form.
 */
ui_exec_function(“user_pcl”, “init”)
 
The first line uses the !!INPUT directive to instruct Patran to find the file named your_custom.pcl, compile it, and add it to the existing set of PCL. By calling ui_exec_function(), Patran is instructed to run the function named “init” in the class named “user_pcl”.
Here is PCL for a file named your_custom.pcl:
CLASS user_pcl
 
 FUNCTION init()
 
 WIDGET menubar_id, usermenu_id, form_id
 
/*
 * Get the id of the Patran menubar.
 */
 menubar_id = uil_primary.get_menubar_id()
 
/*
 * Create the menu.
 */
 usermenu_id = ui_menu_create(menubar_id, “menu_cbk”, “Customer Option”)
 
/*
 * Create an item for the menu.
 */
 ui_item_create(usermenu_id, “my_item”, “Site Specific Item...”, FALSE)
 
/*
 * Create the form. Normally, each form would have it’s own class and
 * it’s own PCL file. But for this example, the form will be created here.
 */
 form_id = ui_form_create(“form”, 3.4, 2.25, “UL”, 3.75, 3.25, @
 “Site Specific Form”, ““)
 
/*
 * Create a label to further identify the form. Notice that once the label
 * is created we no longer need it’s ID, so we ignore the return value.
 */
 ui_label_create(form_id, ““, .75, .25, “Site Specific Application”)
 
/*
 * Create some buttons which could be used to bring up other forms. The
 * separator at the bottom provides a visual separation between the
 * buttons which bring up forms and the button which closes this form.
 */
 ui_button_create(form_id, ““, .25, .75, 3., 0., @
 “Site Specific Geometry Access...”, TRUE, FALSE)
 ui_button_create(form_id, ““, .25, 1.25, 3., 0., @
 “Acoustic Analysis...”, TRUE, FALSE)
 ui_button_create(form_id, ““, .25, 1.75, 3., 0., @
 “Experimental Modal Import...”, TRUE, FALSE)
 
/*
 * Create the button to close the form.
 */
 ui_button_create(form_id, “cancel”, 1.375, 2.5, 1., 0., @
 “Cancel”, TRUE, TRUE)
 
 END FUNCTION
 
 FUNCTION display
 
/*
 * Since the form is not to be displayed unless the menu item is selected,
 * the display() function does not contain a ui_form_display() call. This
 * function exists for completeness.
 */
 
 END FUNCTION
/*
 * This function is called to handle menu events.
 */
 FUNCTION menu_cbk(item_name)
 STRING item_name[]
 
 IF(item_name == “my_item”)THEN
 ui_form_display(“user_pcl”)
 END IF
 
 END FUNCTION
 
/*
 * This function is called to handle Cancel button events.
 */
FUNCTION cancel
 
 ui_form_hide(“user_pcl”)
 
 END FUNCTION
 
END CLASS
The first executable line of the file defines the class to be user_pcl. This class will be referred to in the class and it may also be referred to from other classes. The first function in the file is the init function which creates the widgets to be used in this class. Although it is not required to create all of the widgets here, it is suggested. Notice that since the three widgets declared in the init function are referenced in only that function, they need not be declared CLASSWIDE.
If a PCL file creates a menu, become familiar with the uil_primary.get_menubar_id() function. Refer to User Interface Functions, 297 for detailed information on this function. Once the menubar ID has been returned it may be used as the parent to the menu, and in turn the menu may be used as the parent to the item. The newly created menu and menu item will now appear once this function has been called. This is a picture of part of the customized menubar:
The form is created next. The ID returned from the ui_form_create() function will be used as the parent to the label and the buttons. Notice that the locations and dimensions of the form and the widgets have been done by defining the values specifically rather than using the PCL variables. This was done to how show quickly forms and widgets can be created. Here is a picture of the resulting form:
An empty function named display() is next. Notice that since no arguments are needed for this function, the parentheses are optional. In most classes the display() function will be used to manage the display of the form created in the init() function. These function names are important as documented by ui_exec_function(). This example contains a form that is displayed from a menu pick so the callback function for the menu handles the display of the form.
The next function is named menu_cbk(). This function is the callback function for the menu created in the init() function; notice that the name, menu_cbk, is the same as the second argument in the ui_menu_create() call which is the “callback” argument. One argument is passed to the function, item_name, which is the name of the item that was selected from the menu. Since the menu has only one item there is only one IF...THEN branch (which is unnecessary for this example but is included for completeness). If the item is selected, item_name will be “my_item” which instructs Patran to display the form that was created in the class named “user_pcl.”
The last function in the class is cancel(). This function is also a callback function, this time for the button labelled Cancel (notice that the callback argument for the Cancel button, the second argument, is “cancel” which will be called when the user clicks on the Cancel button). This function simply hides the form.