You are on page 1of 676

C O N T E N T S

MSC.Acumen Toolkit
MSC.Acumen,
Volume
Function
Descriptions
1:
Function Descriptions MSC.Acumen Toolkit,
Function Descriptions

CHAPTER
1
Introduction ■ Introduction, 2
■ General Built-ins, 3
• is_batch, 3
• db_get_p3_version, 3
• utl_get_terse_version, 3
• utl_query_version_level, 4
■ Synchronizing with Startup, Exit, and Database Events, 5
• user_start, 5
• user_quit, 5
• user_db_new, 5
• user_db_open, 6
• user_db_close, 6

2
Model ■ General, 8
• db_get_db_version, 8
• db_get_general_field, 8
• db_get_general_field_length, 9
• db_get_model_file_suffix, 9
■ User Defined, 10
• db_create_client_data, 10
• db_count_client_labels_by_type, 11
• db_count_general_field, 11
• db_get_all_client_data, 11
• db_get_client_data, 12
• db_get_client_id_by_label, 13
• db_get_client_labels_by_type, 13
• db_get_client_label_by_id, 15
• db_get_next_client_entity_label, 15
• db_delete_client_data, 16

3
Files ■ General, 18
• file_is_directory, 18
• get_current_dir, 18
• p3_ps_get_xmt, 18
• set_current_dir, 19
Main Index
• utl_is_locked_file, 19
• utl_lock_file, 20
• utl_unlock_file, 20
• uil_file_open.open_db, 21
■ IGES and CAD Access, 22
• ugi_export_iges_v1, 22
• ugi_import_iges_v3, 22
■ Journal and Session, 25
• jou_file_write, 25
• sf_write_disable, 25
■ Neutral, 26
• neutral_export2, 26
• nf_write, 26
• nf_write2, 27
■ FrameMaker Files, 28
• ui_form_to_frame, 28
• ui_framemaker, 28

4
Graphics ■ General, 30
• ga_error, 30
• verify_boundaries_display_mgr.initialize, 30
• verify_boundaries_display_mgr.plot, 30
• verify_boundaries_display_mgr.erase, 31
■ Element Tables, 32
• ga_elem_scalar_create, 32
• ga_elem_scalar_single_create, 32
• ga_vector_create, 33
• ga_vector_get, 34
• ga_vector_number_get, 35
■ Light Source, 36
• ga_light_attenuation_get, 36
• ga_light_attenuation_set, 36
• ga_light_color_get, 36
• ga_light_color_set, 37
• ga_light_create, 37
• ga_light_delete, 38
• ga_light_direction_get, 38
• ga_light_direction_set, 38
• ga_light_icon_get, 39
• ga_light_icon_set, 39
• ga_light_intensity_get, 40
• ga_light_intensity_set, 40
• ga_light_lights_get, 40
• ga_light_location_get, 41
• ga_light_location_set, 41
• ga_light_movement_get, 42
• ga_light_movement_set, 42
• ga_light_nlights_get, 42
Main Index
• ga_light_nposted_get, 43
• ga_light_post, 43
• ga_light_posted_get, 43
• ga_light_type_get, 44
• ga_light_type_set, 44
• ga_light_unpost, 45
■ Color Look-up Tables, 46
• ga_lookup_colors_get, 46
• ga_lookup_colors_set, 46
• ga_lookup_create, 47
• ga_lookup_current_get, 47
• ga_lookup_current_set, 47
• ga_lookup_delete, 48
• ga_lookup_ncolors_get, 48
• ga_lookup_ntables_get, 49
• ga_lookup_rename, 49
• ga_lookup_tables_get, 49
■ Deformation Plots, 51
• ga_node_deform_create, 51
■ Ranges, 52
• ga_range_contour_get, 52
• ga_range_contour_set, 52
• ga_range_create, 52
• ga_range_delete, 53
• ga_range_exist_get, 53
• ga_range_nranges_get, 54
• ga_range_nvalues_get, 54
• ga_range_ranges_get, 54
• ga_range_rename, 55
• ga_range_startend_set, 55
• ga_range_threshold_set, 55
• ga_range_values_get, 56
• ga_range_values_set, 56
■ Spectrums, 58
• ga_spectrum_colors_get, 58
• ga_spectrum_colors_set, 58
• ga_spectrum_continuous_get, 59
• ga_spectrum_continuous_set, 59
• ga_spectrum_create, 59
• ga_spectrum_current_get, 60
• ga_spectrum_current_set, 60
• ga_spectrum_delete, 61
• ga_spectrum_interpolation_get, 61
• ga_spectrum_interpolation_set, 61
• ga_spectrum_ncolors_get, 62
• ga_spectrum_nspectrums_get, 62
• ga_spectrum_rename, 63
• ga_spectrum_spectrums_get, 63
■ Titles, 64
• ga_title_color_get, 64
• ga_title_color_set, 64
Main Index
• ga_title_create, 64
• ga_title_delete, 65
• ga_title_font_size_get, 65
• ga_title_font_size_set, 66
• ga_title_list_get, 66
• ga_title_loc_get, 66
• ga_title_loc_set, 67
• ga_title_nposted_get, 67
• ga_title_num_get, 68
• ga_title_posted_get, 68
• ga_title_rename, 68
■ Graphics Manager, 69
• db_get_current_viewport_id, 69
• ga_view_normal_get, 69
• gm_convert_name, 69
• gm_conv_device_to_subject, 70
• gm_database_current, 70
• gm_draw_entity, 70
• gm_fit_view, 71
• gm_fullcolor_mode, 71
• gm_graphics_off, 71
• gm_graphics_on, 72
• gm_hilight_clear, 72
• gm_hilight_entity, 72
• gm_hilight_string, 73
• gm_hilight_widget, 73
• gm_lookup_write, 73
• gm_mpeg_pause_recording, 74
• gm_mpeg_resume_recording, 74
• gm_mpeg_start_recording, 74
• gm_mpeg_stop_recording, 75
• gm_viewport_hardware_mode_get, 75
• gm_viewport_hardware_mode_set, 75
• gm_viewport_id_to_name, 76
• gm_viewport_limits_get, 76
• gm_viewport_ncolors_get, 76
• gm_viewport_refresh_off, 77
• gm_viewport_refresh_on, 77
• gm_viewport_refresh_status, 77
• gm_viewport_view_corners, 78
• gm_visibility_all, 78
• gm_visibility_widget, 78
• end_vrml_animation, 79
• gm_write_image, 79
• gm_write_vrml, 80
• start_vrml_animation, 80
■ Clipping Planes, 81
• ga_clip_plane_clip_planes_get, 81
• ga_clip_plane_create, 81
• ga_clip_plane_delete, 81
• ga_clip_plane_direction_get, 82
• ga_clip_plane_direction_set, 82
• ga_clip_plane_icon_get, 83
Main Index
• ga_clip_plane_icon_set, 83
• ga_clip_plane_location_get, 83
• ga_clip_plane_location_set, 84
• ga_clip_plane_movement_get, 84
• ga_clip_plane_movement_set, 85
• ga_clip_plane_nclip_planes_get, 85
• ga_clip_plane_nposted_get, 85
• ga_clip_plane_post, 86
• ga_clip_plane_posted_get, 86
• ga_clip_plane_unpost, 86
• ga_clip_plane_up_set, 87
• clip_plane_ar_calc, 87
• clip_plane_zoom_calc, 88

5
User Interface ■ Error Message Handling, 90
• appcode, 90
• app_db_err_msg, 90
• msg_format_string, 90
• msg_get_application, 91
• msg_string_more, 91
• msg_to_file, 91
• msg_to_string, 92
• user_message, 92
• notemessage.text, 93
■ List Processor, 94
- Include files, 94
• app_count_list, 94
• app_ids_to_vstring, 94
• app_int_array_to_vstring, 95
• asm_u_coord_global_to_local, 95
• asm_u_lp_get_entity_label, 96
• asm_u_lp_get_point, 96
• asm_u_lp_get_vector, 96
• lp_eval_cleanup, 97
• lp_geometry_text, 97
• lp_keyword_text, 98
■ General, 100
• uid_get_screen_info, 100
• uid_get_border_sizes, 100
• uid_get_font_heights, 101
• uid_set_sys_pix, 101
• uil_app_analysis.get_real_name, 101
• uil_pcntcomplete.close, 102
• uil_pcntcomplete.initlz, 102
• uil_primary.get_menubar_id, 102
• ui_sys_command, 103
• ui_sys_return, 103
• ui_text_select, 103
• ui_wid_exit, 104
• ui_wid_hide_forms, 104
Main Index
• ui_exec_command, 104
• ui_form_delete, 104
• ui_form_exists, 105
• ui_form_is_displayed, 105
• ui_graph_create, 106
• ui_is_initialized, 106
• ui_get_client, 106
• ui_get_server, 107
■ Widgets, 108
• ui_clear_focus, 108
• ui_wid_restore_widget, 108
• ui_wid_save_widget, 108
• uil_utils_listbox.select, 109
• uil_utils_listbox.select_none, 109
• uil_utils_listbox.select_list, 109
• uil_utils_listbox.create_list, 110
• uil_utils_listbox.append_list, 110
• uil_utils_listbox.get_selected, 110
• uil_utils_listbox.get_unselected, 111
• uil_utils_listbox.get_all, 111
• uil_utils_listbox.delete_item, 111
• uil_utils_listbox.delete_item_list, 112
• uil_utils_listbox.delete_selected, 112
• uil_utils_listbox.select_all, 112
■ Help, 113
• ui_get_help, 113
• ui_register_help, 113
• ui_add_help, 113

6
Group ■ General, 116
• db_get_group_name, 116
• db_count_entities_in_group, 116
• db_count_groups_for_entity, 116
• db_get_groups_for_entity, 117
• uil_entity_group_members_get, 117
■ FEM, 118
• db_get_groups_using_mpc, 118
• db_count_groups_using_mpc, 118
• db_count_orphan_mpcs, 119
• db_get_orphan_mpcs, 119
• count_orphan_elements, 120
• count_orphan_nodes, 120
• get_orphan_elements, 120
• get_orphan_nodes, 121
• db_add_mpc_to_group, 121
■ Geometry, 122
• db_count_orphan_curves, 122
• db_get_orphan_curves, 122
• db_count_orphan_points, 122
Main Index
• db_get_orphan_points, 123
• db_count_orphan_solids, 123
• db_get_orphan_solids, 123
• db_count_orphan_surfaces, 124
• db_get_orphan_surfaces, 124
• asm_db_count_asm_in_group, 124
• asm_db_get_grids_in_group, 125
• asm_db_get_hpats_in_group, 125
• asm_db_get_lines_in_group, 126
• asm_db_get_patches_in_group, 126
• sgm_db_count_iges_in_group, 127
• sgm_db_get_iges_in_group, 127
■ Graphics Application, 129
• ga_groups_load_vector_set, 129
• ga_group_color_get, 129
• ga_group_color_set, 130
• ga_group_current_get, 130
• ga_group_deform_get, 130
• ga_group_deform_set, 131
• ga_group_display_get, 131
• ga_group_elem_scalar_get, 132
• ga_group_elem_scalar_set, 132
• ga_group_entities_get, 132
• ga_group_exist_get, 133
• ga_group_groups_get, 133
• ga_group_label_get, 135
• ga_group_label_set, 135
• ga_group_load_vector_get, 135
• ga_group_load_vector_set, 136
• ga_group_nentities_get, 136
• ga_group_ngroups_get, 137
• ga_group_node_deform_set, 137
• ga_group_precision_get, 138
• ga_group_result_vector_get, 138
• ga_group_result_vector_set, 138
• ga_group_selectable_get, 139
• ga_group_selectable_set, 139
• ga_group_style_get, 140
• ga_group_style_set, 140
• ga_group_vector_load_get, 140
• ga_group_vector_load_set, 141
• ga_group_vector_result_get, 141
• ga_group_vector_result_set, 142

7
Geometry ■ General, 144
• db_get_geom_type, 144
• sgm_db_get_blob_size, 144
• sgm_db_get_company_of_origin, 145
• sgm_db_modify_entity_label, 146
• sgm_incongruent_geom_exist, 146

Main Index
• sgm_incongruent_geom_display, 146
• sgm_incongruent_geom_seg_exit, 147
• sgm_u_calc_mscale_mat, 147
• asm_u_coord_global_to_local, 147
■ Point, 149
• asm_db_create_grid, 149
• db_count_point, 149
• db_get_max_point_label, 150
• db_get_min_point_label, 150
• db_get_point_association_count, 150
• db_get_point_id, 151
• db_get_point_label, 151
• db_get_point_coo_and_type, 151
• asm_db_get_next_grid_label, 152
• sgm_db_get_point, 152
• sgm_edit_point_equivalence, 152
• sgm_get_close_points, 153
• sgm_node_on_point, 154
■ Curve, 155
• asm_db_get_curve_geo, 155
• asm_db_get_next_line_label, 155
• asm_const_curve_2d_arc2point_v2, 155
• asm_const_curve_2d_arc3point_v1, 158
• asm_const_curve_2d_circle_v1, 158
• asm_const_curve_project_v1, 159
• curve_arc_to_parm, 160
• curve_parm_to_arc, 161
• db_count_curve, 161
• db_get_curve_coo_and_type, 162
• db_get_curve_id, 162
• db_get_curve_label, 162
• db_get_max_curve_label, 163
• db_get_min_curve_label, 163
• sgm_associate_nodes_curve, 164
• sgm_const_curve_project_v1, 164
• sgm_create_curve_on_surface, 165
• sgm_curve_convert_s_to_u, 166
• sgm_curve_convert_u_to_s, 166
• sgm_curve_evaluate, 167
• sgm_db_get_curve, 168
• sgm_db_get_curve, 168
• sgm_get_arc_center_radius, 168
• sgm_get_curve_length, 169
• sgm_node_on_curve, 169
• sgm_show_angle_between_curves, 170
■ Surface, 171
• asm_db_get_next_patch_label, 171
• db_count_surface, 171
• db_get_max_surface_label, 171
• db_get_min_surface_label, 172
• db_get_surface_coo_and_type, 172
• db_get_surface_id, 172
Main Index
• db_get_surface_label, 173
• sgm_create_surface_composite_c, 173
• sgm_create_surface_comptrim_v1, 174
• sgm_create_surface_from_elems1, 175
• sgm_db_get_num_loops_face, 176
• sgm_db_get_surface, 176
• sgm_edit_surface_edge_match, 177
• sgm_edit_surface_sew, 177
• sgm_get_surface_area, 178
• sgm_node_on_surface, 178
• sgm_show_surface_normals, 179
• sgm_surface_evaluate, 180
■ Solid, 182
• db_count_solid, 182
• db_get_max_solid_label, 182
• db_get_min_solid_label, 182
• db_get_solid_coo_and_type, 183
• db_get_solid_id, 183
• db_get_solid_label, 183
• asm_db_get_next_hpat_label, 184
• sgm_construct_solid_brep, 184
• sgm_construct_solid_volume, 184
• sgm_db_get_num_vertices_body, 185
• sgm_db_get_solid, 185
• sgm_edit_brep_break_plane_v1, 186
• sgm_edit_brep_break_surface_v1, 186
• sgm_edit_solid_break, 187
• sgm_edit_solid_refit_v1, 187
• sgm_edit_solid_reverse, 188
• sgm_get_solid_volume, 188
• sgm_solid_evaluate, 188
• sgm_verify_solid_brep, 189
■ Coordinate Frame, 190
• app_db_get_ref_cid, 190
• asm_u_coord_local_to_global, 190
• db_check_coord_frame_exist, 191
• db_count_coordinate_frame, 191
• db_get_all_coord_frame_ids, 191
• db_get_next_coord_frame_ids, 192
• db_get_max_coord_label, 192
• db_get_min_coord_label, 193
• db_get_all_posted_coord, 193
• db_get_next_posted_coord, 194
• asm_db_get_next_cord_label, 194
• db_get_coord_frame_label, 195
• db_get_current_coord, 195
■ Point/Curve Relation, 196
• db_count_curves_for_point, 196
• db_get_curves_for_point, 196
• sgm_db_get_edge_vertex_ids, 196
• sgm_nearest_point_on_curve, 197
• sgm_nearest_point_on_curve_aea, 197
Main Index
• xy_curve_num_points_get, 198
■ Curve/Surface Relation, 199
• db_count_surfaces_for_edge, 199
• db_get_surfaces_for_edge, 199
• sgm_db_get_gen_face_edge_ids, 199
• sgm_db_get_gen_face_vertex_ids, 200
• sgm_db_get_num_edges_face, 200
■ Surface/Solid Relation, 201
• db_count_solids_for_surface, 201
• db_get_solids_for_surface, 201
• sgm_db_get_gen_body_face_ids, 201
• sgm_db_get_gen_body_vertex_ids, 202
• sgm_db_get_num_faces_body, 202
■ Transform, 203
• transform_pts, 203

8
Finite Element ■ Finite Elements, 206
Model • db_get_next_elem_id, 206
• db_get_min_elem_id, 206
• db_get_max_elem_id, 206
• fem_get_elem_assoc_groups, 207
• fem_get_elem_ids, 207
• fem_u_get_free_edges, 208
• fem_u_get_free_faces, 208
• db_update_elem_ids, 209
• db_count_elems_for_geo, 209
• db_update_elem_types, 210
• db_count_elem_topology_codes, 210
• db_count_elem_w_topology, 210
• db_count_nodes_for_geometry, 211
• db_get_elems, 211
• db_get_elems_by_lbc, 212
• db_get_elem_config_ntl, 212
• db_get_elem_dimens, 213
• db_get_elem_for_geo_type_and_id, 214
• db_get_elem_shape_for_id, 214
• db_get_elem_topology_codes, 215
• db_get_elem_topos_for_geom, 215
• db_get_elem_top_name, 215
• db_get_elem_verification_parms, 216
• db_get_etop_for_a_code, 216
• db_get_indep_nodes_in_sub_mpc, 217
■ MPCs, 218
• db_get_next_mpc_id, 218
• fem_get_mpc_assoc_nodes, 218
• fem_get_mpc_ids, 219
• db_count_valid_dofs_f_mpc_type, 219
• db_validate_mpc, 220
• db_count_valid_mpc_types, 220
Main Index
• db_get_all_valid_dof_f_mpc_type, 221
• db_get_nxt_valid_dof_f_mpc_type, 221
• db_get_all_valid_mpc_type, 221
• db_get_next_valid_mpc_type, 222
• db_get_dep_nodes_in_sub_mpc, 222
• db_get_dof_id, 223
• db_get_dof_name, 224
• db_get_mpc_type_id, 224
• db_get_mpc_type_name, 224
• db_get_valid_mpc_ids_in_group, 225
• fem_get_mpc_assoc_groups, 225
■ Nodes, 227
• db_get_nodal_association, 227
• db_get_node, 227
• db_get_nodes_by_lbc, 228
• db_get_nodes_for_geometry, 228
• db_get_next_node_id, 229
• db_get_min_node_id, 229
• db_get_max_node_id, 229
• fem_get_node_assoc_groups, 230
• fem_get_node_ids, 230
• db_verify_nodes_exist, 231
• db_count_unref_nodes, 231
• db_get_unreferenced_node_ids, 232
■ Mesh, 233
• fem_create_mesh_sol_3, 233
• fem_seed_display_dir_arrows, 233
• db_get_mesh_params, 234
• move_mesh, 234
• move_mesh_1, 235
■ Element/Node Relations, 236
• db_count_elems_using_node, 236
• db_count_mpcs_using_node, 236
• db_count_nodes_in_mpc, 237
• db_get_elems_using_nodes, 237
• db_get_elem_nodes, 238
• db_get_nodes_in_mpc, 238
• list_get_node_ass_el_edge, 239
• list_get_node_ass_el_face, 239
• list_get_node_ass_elem, 239
• list_get_node_ass_geo, 240
• list_get_node_ass_group, 240
• list_get_node_ass_mpc, 240
• list_get_node_att_fringe, 241
• list_get_node_att_value, 241

9
Load Cases ■ General, 244
• db_activate_load_case, 244
• db_delete_load_case, 244

Main Index
• db_find_load_case_id, 245
• db_count_load_cases, 245
• db_get_all_load_case_names, 245
• db_get_all_load_cases, 246
• db_get_next_load_case, 246
• db_get_lc_id_given_job_seq, 247

10
Element ■ General, 250
Properties • bl_create_std_beam_section, 250
• bl_get_std_beam_section_data, 250
• bl_modify_std_beam_section, 251
• blcomputeprincaxespoints, 251
• blgetalpha, 252
• blgetbuttonicon, 252
• blgetcenters, 252
• blgetdimfieldid, 253
• blgetdimvalue, 253
• blgetlabelicon, 253
• blgetlabels, 254
• blgetnumdimension, 254
• blgetnumplotpoints, 254
• blgetnumplotpointsbyid, 255
• blgetnumtypeinfo, 255
• blgetperim, 255
• blgetplotpoints, 256
• blgetplotpointsbyid, 256
• blgetplotpointsbyid2, 257
• blgetprop, 258
• blgetproplabels, 259
• blgettypeinfo, 259
• blmodifybeamdimension, 259
• db_create_selected_etype, 260
• db_count_elem_type, 261
• db_count_etop_for_a_code, 261
• db_get_all_dof_set_names, 261
• db_get_next_dof_set_names, 262
• db_get_all_form_opt_code_names, 262
• db_get_next_form_opt_code_names, 263
• db_get_all_geo_opt_code_names, 263
• db_get_next_geo_opt_code_names, 264
• db_get_all_lam_opt_code_names, 264
• db_get_next_lam_opt_code_names, 265
• db_get_region_for_geometry, 265
• db_get_region_ids_and_names, 266
• db_get_elements_in_region_exp, 266
• db_get_etop_for_a_code, 267
• db_get_a_phys_prop_w_nord, 267
• db_create_phys_prop_set_defn, 268
• db_get_phys_prop_set_defn, 268
• db_get_allowable_phys_prop, 269
• db_get_selected_prop_set, 270
Main Index
• db_delete_phys_prop_region, 270
• db_associate_geo_to_region, 271
• db_count_geo_in_region, 272
• db_get_geo_in_region, 272
• db_count_elements_in_region_exp, 273
• db_create_anl_elm_summary, 273
• db_get_anl_elm_summary, 274
• db_delete_anl_elm_summary, 274
• db_create_analysis_elements, 275
• db_delete_analysis_elements, 275
• db_get_analysis_elements, 276
• db_get_all_elem_defn, 276
• db_get_next_elem_defn, 277
• db_bulk_get_possible_dof_sets2, 277
• db_bulk_get_possible_lam_opts2, 278
• db_bulk_get_possible_form_opts2, 279
• db_bulk_get_possible_dof_sets1, 279
• db_bulk_get_possible_lam_opts1, 280
• db_bulk_get_possible_geo_opts1, 280
• db_bulk_get_possible_form_opts1, 281
• db_bulk_get_selected_etops_mat, 281
• db_bulk_get_possible_matl_dirs, 282
• db_bulk_get_possible_matl_lins, 283
• db_get_all_pp_ids_and_names, 284
• db_get_next_pp_ids_and_names, 284
• db_set_comp_lam, 285

11
Loads and ■ General, 288
Boundary • lbc_create, 288
Conditions • lbc_delete, 289
• lbc_eval_fem_by_lc, 289
• lbc_eval_fem_lbc, 289
• lbc_get_sdbx_datatype, 290
• lbc_gm, 290
• lbc_graphics_defn, 291
• lbc_lp_parse_sca, 291
• lbc_lp_parse_vec, 292
• lbc_plot_markers, 293
• lbc_show_plot_scalar, 293
• loadcase_create2, 294
• loadsbcs_get_appl_region_list, 294
• loadsbcs_lp_coord, 295
■ Database, 296
• db_bulk_get_lbc_ds, 296
• db_bulk_get_lbc_dv, 296
• db_bulk_get_lbc_ss, 297
• db_bulk_get_lbc_sv, 298
• db_count_appl_geo_region, 298
• db_count_lbc, 299
• db_count_lbc_appl_region_entity, 299

Main Index
• db_count_lbc_types, 300
• db_count_loads_for_element, 300
• db_count_load_cases_with_lbc, 300
• db_delete_lbc, 301
• db_delete_lbc_defn, 301
• db_get_all_appl_geo_regions, 301
• db_get_next_appl_geo_region, 302
• db_get_all_appl_reg_defns, 302
• db_get_next_appl_reg_defn, 303
• db_get_all_lbcs_new, 303
• db_get_next_lbcs_new, 303
• db_get_all_lbc_names, 304
• db_get_next_lbc_name, 304
• db_get_all_lbc_names_by_type, 305
• db_get_next_lbc_name_by_type, 305
• db_get_all_lbc_type_defns, 306
• db_get_next_lbc_type_defn, 306
• db_get_all_lbc_type_names, 307
• db_get_next_lbc_type_name, 308
• db_get_all_lbc_var_defns, 308
• db_get_next_lbc_var_defn, 308
• db_get_lbc_id, 309
• db_get_lbc_name, 309
• db_get_lbc_type_defn, 310
• db_get_lbc_var_defn, 311
• db_get_loads_for_element, 311
• db_get_load_cases_with_lbc, 312
• db_get_valid_cat_by_type, 312
• db_get_valid_eldim_by_type_cat, 313
• db_get_valid_lbc_var_ids, 313
• db_modify_load_case, 314

12
Materials ■ Database, 316
• db_bulk_get_possible_cond_opts1, 316
• db_bulk_get_possible_cond_opts2, 316
• db_bulk_get_possible_dof_sets, 317
• db_get_constitutive_model, 318
• db_get_valid_const_models_count, 318
• db_get_valid_const_models, 319
• db_mo_const_models_specified, 319
• db_delete_matl_const_model, 320
• db_get_matl_category, 320
• db_get_valid_mtl_category_cnt, 321
• db_get_valid_mtl_categories, 321
• db_create_mtl_allowable_magics, 322
• db_get_mtl_allowable_magic_cnt, 322
• db_count_options, 323
• db_get_mtl_allowable_magics, 323
• db_get_mtl_magics, 324
• db_get_mtl_magics_count, 324
• db_get_mtl_magics_defn, 325
Main Index
• db_get_mtl_magics_options, 325
• db_get_material_name_from_id, 326
• db_get_material_id_from_name, 326
• db_count_materials, 326
• db_get_all_material_names, 327
• db_get_next_material_name, 327
• db_modify_material, 328
• db_delete_material, 328
• db_get_all_cond_opt_code_names, 329
• db_get_next_cond_opt_code_names, 329
• db_get_all_lam_opt_code_names, 330
• db_get_next_lam_opt_code_names, 330
• db_get_allowable_matl_prop, 331
• db_get_all_allow_matl_prop_cnt, 331
• db_get_allowable_matl_prop_cnt, 332
• db_get_all_allowable_matl_prop, 332
• db_get_matl_prop_alias, 333
• db_get_matl_prop_defn, 333
• db_modify_matl_prop_value, 334
• db_delete_material_property, 334
• db_get_comp_hal, 335
• db_get_comp_sfc, 335
• mat_3d_ani_to_3d_ort, 336
• engin_cons_to_elastic_matrix, 337
• mat_2d_ani_to_2d_ort, 337
• get_qab_from_engin_cons, 338
• n21_cons_to_sym_6x6_matrix, 338
• mat_load_show, 339
• mat_hal_load_defn_show, 340
• mat_lam_load_defn_show, 341
• mat_mix_load_defn_show, 341
• mat_sfc_load_defn_show, 342
• material.namedelete, 343
■ Laminate Modeler, 344
• p3cm.close_2, 344
• p3cm.create_book_layup2, 344
• P3cm.create_laminates_layup_2, 345
• p3cm.create_layup_add_2, 346
• p3cm.create_material_add, 347
• p3cm.create_ply_add_2, 348
• p3cm.create_results_failure, 349
• p3cm.create_results_mid_sort, 349
• p3cm.create_results_sort, 350
• p3cm.delete_laminates, 350
• p3cm.delete_material_name, 351
• p3cm.delete_ply_name, 351
• p3cm.delete_propsets, 351
• p3cm.import_model_file_2, 352
• p3cm.import_plies_file_2, 352
• p3cm.modify_material, 353
• p3cm.modify_ply, 353
• p3cm.new, 354
• p3cm.set_offsets, 355

Main Index
• p3cm.open, 355
• p3cm.save_as_2, 356
• p3cm.set_export_options_2, 356
• p3cm.set_graphics_options_2, 357
• p3cm.set_tolerance, 357
• p3cm.show_laminate, 358
• p3cm.show_layup_exploded, 359
• p3cm.show_ply, 359

13
Analysis ■ General, 362
• analysis_get.pset_for_job, 362
• analysis_import, 362
• analysis_main.job_name_lbox, 363
• analysis_main.user_function, 363
• analysis_submit, 364
• analysis_submit_2, 365
• db_set_pref, 366
• db_get_job_info, 367
• db_set_model_file_suffix, 367
• db_set_results_file_suffix, 368
• db_set_default_anal_code, 368
• db_get_default_anal_code, 369
• db_get_anal_code_name, 369
• db_get_anal_code_id, 369
• db_count_anal_codes, 370
• db_get_all_anal_codes, 370
• db_get_next_anal_code, 371
• db_set_default_anal_type, 371
• db_get_default_anal_type, 372
• db_get_anal_type_name, 372
• db_get_anal_type_id, 372
• db_count_anal_types, 373
• db_get_all_anal_types, 373
• db_get_next_anal_type, 374
• db_get_at_for_ac, 374
• db_set_at_for_ac, 375
• db_create_job_name_for_a_code, 375
• db_count_job_names_for_a_code, 376
• db_get_jobnames_for_a_code, 376
• db_update_jobname_for_a_code, 377
• db_create_job_name_list, 378
• db_create_job_name_list_entry, 378
• db_get_jobname_list_entries, 379
• db_count_job_name_list_entry, 379
• db_delete_job_name_list, 380
• db_create_job_name, 380
• db_assign_last_jobname, 380
• db_get_last_jobname, 381
• db_get_job_name_given_id, 381
• db_count_all_job_name_ids, 382
• db_get_all_job_name_ids, 382
Main Index
• db_get_all_job_names, 383
• db_get_next_job_name, 383
• db_get_id_given_job_name, 383
• db_get_id_given_job_name_code, 384
• db_get_id_given_load_case_name, 384
• db_delete_job_name, 385
• db_create_analysis_step, 385
• db_get_analysis_steps, 386
• db_get_steps_for_a_job, 386
• db_get_step_info, 387
• db_count_analysis_steps, 388
• db_count_steps_for_a_job, 388
• db_get_id_given_step_name, 388
• db_update_analysis_step, 389
• db_delete_analysis_step_id, 389
• db_create_param_set_entry, 390
• db_count_param_set_entries, 391
• db_get_param_set_entry, 391
• db_get_param_set_ent_pcl, 392
• db_get_param_set_entries, 392
• db_delete_param_set_entry, 393
• db_delete_param_set_entries, 393
• db_create_pset_matrix_entry, 394
• db_get_pset_matrix_entry, 394
• db_get_pset_matrix_size, 395
• jobfile.close, 395
• jobfile.create_matrix, 396
• jobfile.open, 396
• jobfile.set_job_status, 397
• jobfile.writec, 397
• jobfile.writei, 398
• jobfile.writer, 398
• jobfile.write_spl, 399
• msc_delete_old_files, 399
• mscnastran_anlyze_sub_create.available_callback, 400
• mscnastran_analyze_tp.get_version_number, 400
• mscnastran_job.associate_subcases, 400
• mscnastran_subcase.create, 401
• mscnastran_subcase.create_char_param, 401
• mscnastran_update.job, 402
• uil_app_analysis.change_current_branch, 402

14
Fields ■ General, 404
• db_get_all_field_names, 404
• db_get_next_field_name, 404
• db_get_field_id, 405
• db_get_field_attrs, 405
• fields_create_general_term, 406
• get_field_values_no_trans, 408
• get_field_values, 408
• db_get_max_field, 409
Main Index
• fld_evl_get_maxnod_for_group, 409
• db_modify_field, 410
• db_delete_field, 411
• fld_cre_fem_res_sca, 411
• fld_cre_fem_res_vec, 411
• db_delete_field_res, 412
• field_create_field_lbc, 412
• db_get_field_lbc, 413
• db_get_field_lbc_type, 414
• field_fem_const_eval, 414
• db_get_field_dfem, 415

15
Results ■ General, 418
• db_count_result_types_for_elem, 418
• db_get_results_file_suffix, 418
• db_get_elem_scalar_name, 419
• jobfile.create_jobname, 419
• jobfile.create_param, 420
• jobfile.eval_list, 420
• jobfile.write_array_as_list, 421
• jobfile.write_element_list, 421
• jobfile.write_integer_list, 422
• jobfile.write_node_list, 422
• jobfile.write_real_list, 422
• jobfile.write_stream, 423
• jobfile.write_string, 423
• jobfile.writer, 424
• jobfile.writeS1, 424
• jobfile.writeS2, 424
• jobfile.writeS3, 425
• jobfile.writeS4, 425
• jobfile.writeSS, 425
• rdm_result_minmax_get, 426
• res_db_cgetlayerposids, 426
• res_db_cgetrescases, 427
• res_utl_create_elem_result, 427
• res_utl_extract_elem_history2, 428
• res_utl_extract_elem_results2, 429
• res_utl_extract_nodal_history2, 431
• res_utl_extract_nodal_results2, 432
• res_utl_transform_nodal_results, 433
• vki_db_getresid, 434
• xy_curve_results_set_wnd, 434

16
Preferences ■ Database, 436
• db_get_pref, 436
• db_add_pref, 436
■ General, 438
Main Index
• pref_anal_get, 438
• pref_anal_set, 438
• pref_confirm_get, 439
• pref_display_method_get, 439
• pref_entity_dp_get, 439
• pref_entity_dp_set, 440
• pref_env_get_integer, 440
• pref_env_get_logical, 441
• pref_env_get_real, 441
• pref_env_get_string, 442
• pref_fa_get, 442
• pref_fa_set, 443
• pref_geo_cid_int_string, 445
• pref_geo_cid_string_int, 445
• pref_geo_get, 446
• pref_get_anal_attributes, 446
• pref_get_anal_code_count, 447
• pref_get_anal_type_count, 447
• pref_get_next_anal_code, 448
• pref_get_next_anal_type, 448
• pref_global_get, 448
• pref_graphics_get, 449
• pref_graphics_marker_data_get, 450
• pref_entity_set, 450

17
Utilities ■ Arrays, 454
• array_copy_real, 454
• array_del_zero_int, 454
• array_fill_int, 454
• array_fill_zero_int, 455
• array_fill_zero_real, 455
• array_real_fill_null, 455
• array_sort_and_del_dupl_int, 456
■ Math, 457
• math_get_no_data_null, 457
• math_is_no_data_null, 457
• math_mat_add, 458
• math_mat_invert, 458
• math_mat_mult, 458
• math_mat_transp_in_place, 459
• math_vec_len, 459
• math_vec_norm, 459
• mth_vec_add, 460
• mth_vec_cross_prod, 460
• mth_vec_dot_prod, 460
• mth_vec_length, 461
• mth_vec_scale, 461
• util_equal_real, 461
• util_real_equal_null, 462
• util_rounder, 462

Main Index
■ RPCs, 463
• rpc_add_server, 465
• rpc_init_client, 466
• rpc_call, 466
• rpc_timeout, 467
• rpc_put_bool_array, 467
• rpc_put_int_array, 467
• rpc_put_real_array, 468
• rpc_put_boolean, 468
• rpc_put_command, 469
• rpc_put_integer, 469
• rpc_put_real, 469
• rpc_put_status, 470
• rpc_put_string, 470
• rpc_clear_output, 471
• rpc_get_bool_array, 471
• rpc_get_int_array, 471
• rpc_get_real_array, 472
• rpc_get_boolean, 472
• rpc_get_command, 473
• rpc_get_integer, 473
• rpc_get_real, 474
• rpc_get_status, 474
• rpc_get_string, 475
• rpc_inquire_count, 475
• rpc_inquire_item, 475
■ Security, 477
• sec_is_product_in_matrix, 477
• sec_is_product_licensed, 477
• sec_license_type, 477
■ Strings, 479
• string_newline_count, 479
• string_newline_position, 479
• ga_entities_string_format, 480
• ga_entity_get_by_type, 480
• uil_list_union_expr, 481
■ Performance, 482
• timer_on, 482
• timer_off, 482

18
Obsolete, ■ General, 484
Modified, and ■ Functions for Chapter 1, 485
Broken Functions
• utl_get_terse_version, 485
■ Model (Chapter 2), 486
• db_delete_client_label, 486
• db_reset_client_info, 486
■ Files (Chapter 3), 489
• get_current_dir, 489
Main Index
• utl_is_locked_file, 490
• sf_write_disable, 491
• ui_form_to_frame, 491
• ugi_export_iges_v1, 492
■ Graphics (Chapter 4), 494
• ga_elem_scalar_delete, 494
• ga_elem_scalar_get, 496
• ga_elem_scalar_minmax_get, 499
• ga_elem_scalar_number_get, 501
• ga_vector_delete, 503
• gm_animate_end, 506
• gm_animate_loadcase_parms, 507
• gm_animate_start, 507
• gm_database_close, 508
• gm_database_open, 509
• gm_pick, 511
• gm_pick_abort, 511
• gm_pick_add, 513
• gm_pick_add_widget, 515
• gm_pick_adjust_hilight, 517
• gm_pick_clear, 518
• gm_pick_filter, 520
• gm_pick_notify, 523
• gm_pick_reject, 525
• gm_pick_reset_level_counter, 526
• gm_uiwindow_create, 527
• gm_uiwindow_delete, 527
• gm_viewport_auto_off, 527
• gm_viewport_auto_on, 528
• gm_viewport_plot, 530
• gm_window_id_get, 532
• gm_xy_plot, 533
■ User Interface (Chapter 5), 536
• msg_format_string, 536
• msg_to_file, 537
• app_count_list, 538
• lp_eval_cleanup, 539
• lp_keyword_text, 539
• ui_flush, 540
• ui_flush_events, 540
• ui_sys_return, 541
• ui_text_select, 541
• ui_window_create, 542
• ui_helpmenu_create, 542
• ui_abortwidget_create, 543
• ui_wid_restore_widget, 544
• ui_wid_save_widget, 544
• uil_primary_file.enable_entire_menu, 545
• uil_primary_file.enable_item, 545
• uil_primary_pref.enable_item, 545
• uil_utils_listbox.select_list, 546
• uil_utils_listbox.create_list, 547
• uil_utils_listbox.append_list, 548
Main Index
• uil_utils_listbox.select_one, 549
• uil_utils_listbox.select, 549
■ Group (Chapter 6), 550
• db_count_entities_in_group, 550
• ga_group_ngroups_get, 551
• db_get_orphan_mpcs, 551
• count_orphan_elements, 551
• db_add_mpc_to_group, 552
• db_get_orphan_curves, 553
• db_get_orphan_points, 553
• db_get_orphan_solids, 554
• db_get_orphan_surfaces, 554
• ga_group_selectable_set, 555
• sgm_db_get_iges_in_group, 556
■ Geometry (Chapter 7), 558
• asm_db_get_next_grid_label, 558
• asm_db_get_next_line_label, 559
• asm_db_get_next_patch_label, 560
• sgm_show_surface_normals, 561
• asm_db_get_next_hpat_label, 562
• sgm_db_get_solid, 563
• sgm_verify_solid_brep, 564
• app_db_get_ref_cid, 564
• asm_db_get_next_cord_label, 565
• db_get_all_coord_frame_ids, 566
• db_get_current_coord, 567
• db_get_surfaces_for_edge, 568
• db_get_solids_for_surface, 569
■ Finite Element Model (Chapter 8), 570
• db_get_elems_by_lbc, 570
• db_get_node, 570
• fem_get_node_ids, 571
• fem_seed_display_dir_arrows, 572
■ Load Cases (Chapter 9), 573
• db_delete_load_case, 573
■ Element Properties (Chapter 10), 574
• db_get_next_lam_opt_code_names, 574
• db_del_geo_assoc_to_region, 574
■ Loads and Boundary Conditions (Chapter 11), 575
• lbc_create, 575
• lbc_get_sdbx_datatype, 577
• lbc_lp_parse_sca, 578
• lbc_show_plot_marker, 579
• lbc_plot_markers, 579
• lbc_show_plot_scalar, 579
• loadsbcs_get_appl_region_list, 581
• db_count_lbc_in_group, 582
• db_get_all_lbcs, 582
• db_get_all_lbcs_new, 582
• db_get_next_lbc, 583

Main Index
• db_get_next_lbcs_new, 583
• db_get_all_lbcs_in_group, 583
• db_get_all_lbc_var_defns, 584
• db_get_lbc_type_defn, 585
• db_get_lbc_var_defn, 586
■ Materials (Chapter 12), 588
• mat_2d_ani_to_2d_ort, 588
■ Analysis (Chapter 13), 589
• analysis_get.pset_for_job, 589
• db_get_anal_type_name, 590
• db_get_anal_type_id, 591
• db_get_pset_matrix_entry, 592
■ Fields (Chapter 14), 593
• db_modify_field, 593
• db_create_field_res, 595
• db_get_field_dfem, 596
• field_create_field_lbc, 597
• db_get_field_lbc, 598
■ Results (Chapter 15), 600
• db_count_result_types_for_elem, 600
■ Preferences (Chapter 16), 601
• pref_env_get_string, 601
■ Utilities (Chapter 17), 602
• rpc_clear_timeout, 602
• util_round, 602

INDEX MSC.Acumen Toolkit 605

Main Index
Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Introduction
1
■ Introduction
■ General Built-ins
■ Synchronizing with Startup, Exit, and Database Events

Main Index
2
Function Descriptions

1.1 Introduction
MSC.Patran is composed of compiled code (either C or FORTRAN) which is the MSC.Patran
executable and PCL programs which are delivered in the p3patran.plb library file. PCL makes
up a significant portion of the MSC.Patran functionality. In fact, p3patran.plb contains more
than 44,000 routines at last count! PCL interacts with the compiled code through “wrappers.” A
wrapper is a special type of C function which allows PCL to call the compiled code directly.
Sometimes, the functions which are in wrappers are called “Built-ins” which is similar to an
intrinsic function in traditional programming languages. Wrappers can only be created at
compile time, so you, the PCL programmer cannot add any additional “Built-ins” at your site.
Fortunately, the programmers here at The MSC.Software Corporation had the foresight to add
numerous useful PCL built-ins which are documented here and are in addition to the current
functions described in PCL and Customization, PCL and Customization (p. i) in the and PCL
Reference Manual delivered in the standard product.
The Extended PCL Functions Manual includes functions for model (database), files, graphics,
user-interface, groups, geometry, fem, loadcases, element properties, loads, materials, results,
utilities and much more.

Main Index
CHAPTER 1 3
Introduction

1.2 General Built-ins


The following functions set and return information regarding the MSC.Patran session or
MSC.Patran itself.

is_batch ()

Description:
Checks to see if MSC.Patran is running in batch mode.
Input:
none
Output:
LOGICAL <Return Value> TRUE if running in batch mode.
FALSE if running interactively.
Example:
Please see is_batch (p. 2) in the MSC.Acumen, Volume 2: Code Examples.

db_get_p3_version ( p3_ver)

Description:
Queries the database for the version number.
Input:
none
Output:
STRING p3_ver[] Buffer to hold MSC.Patran version.
INTEGER <Return Value> SQL error code.
Example:
Please see db_get_p3_version (p. 2) in the MSC.Acumen, Volume 2: Code Examples.

utl_get_terse_version ( terse_verson )

Description:
Get terse (short) version string.
Input:
none
Output:
STRING terse_verson[] Version string.
Example:
Please see utl_get_terse_version (p. 6) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
4
Function Descriptions

utl_query_version_level ()

Description:
Return the code version level.
Input:
none
Output:
INTEGER <Return Value> 0 = Production code.
1 = Beta code.
2 = Alpha code.
3 = Development code.
Example:
Please see utl_query_version_level (p. 6) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 1 5
Introduction

1.3 Synchronizing with Startup, Exit, and Database Events


When certain operations occur in MSC.Patran callbacks to some PCL routines will occur. These
PCL routines are not defined by the MSC.Software Corporation and if they do not exist, then the
calls will not be made. The user is welcome to create these routines to perform whatever function
is desired. Some examples are generating accounting information or initializing or hiding user
defined forms. The following PCL functions can be defined by the user. In the function
description is information on when this function will be called by the MSC.Patran system.

user_start ()

Description:
Called just after startup of MSC.Patran. No arguments are given to the function and there is no
return result.
Input:
none
Output:
none
Example:
Please see user_start (p. 5) in the MSC.Acumen, Volume 2: Code Examples.

user_quit ()

Description:
Called just before exit of MSC.Patran. No arguments are given to the function and there is no
return result.
Input:
none
Output:
none
Example:
Please see user_quit (p. 5) in the MSC.Acumen, Volume 2: Code Examples.

user_db_new ( dbname, tmplname)

Description:
Called just after a new database is created.
Input:
STRING dbname[] Name of database that was created.
STRING tmplname[] Name of the template file used for the database.
Output:
none
Example:
Please see user_db_new (p. 3) in the MSC.Acumen, Volume 2: Code Examples.
Main Index
6
Function Descriptions

user_db_open ( dbname )

Description:
Called just after an existing database is opened.
Input:
STRING dbname[] Name of database that was opened.
Output:
none
Example:
Please see user_db_open (p. 4) in the MSC.Acumen, Volume 2: Code Examples.

user_db_close ( dbname, isquit )

Description:
Called just before a database is closed.
Input:
STRING dbname[] Name of database that was created.
LOGICAL isquit TRUE if quit, FALSE if close.
Output:
none
Example:
Please see user_db_close (p. 3) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Model
2
■ General
■ User Defined

Main Index
8
Function Descriptions

2.1 General
The following routines return general information and allow manipulation of the model file.

db_get_db_version (db_ver)

Description:
Retrieves the database version.
Input:
none
Output:
STRING db_ver[] Database version. Success or failure of routine.
INTEGER <Return Value> SQL error code.
Example:
Please see db_get_db_version (p. 625) in the MSC.Acumen, Volume 2: Code Examples.

db_get_general_field ( <field_id >,<term_id>,<field_data_length>,<term_field_id>,


<term_function_type>, <field_data>)

Description:
This function returns term_field_id, term_function_types and field_data from the field form.
The input to the function are the field_id, term_id and the length of the field data. It returns a
positive integer indicating the status of the execution of the function.
Input:
INTEGER field_id The id of the field.
INTEGER term_id Term order of creation in the general field.
INTEGER field_data_length Length of the expression stored.
Output:
INTEGER term_field_id Field id of the term
INTEGER term_function_type Function type id
0 - Field expression.
1 - Utility functions.
2 - PCL Math Built-Ins.
3 - PCL String Built-Ins.
STRING field_data[] String containing the field expression.
INTEGER <return value> 0 for success and 1 for failure
Error Conditions:
None.
Example:
Please see db_get_general_field (p. 625) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 2 9
Model

db_get_general_field_length ( <field_id >, <count>,<term_id>,<field_data_length>)

Description:
This function returns the term_id and field_data_length of the field_id from which the length of
field is required. It returns a positive integer indicating the status of the execution of the
function, 0 for success.
Input:
INTEGER field_id The id of the field.
INTEGER count The count of term_ids in the field.
Output:
INTEGER term_id() The term id's for the field.
ARRAY
INTEGER field_data_length() Length of the strings of the field data.
ARRAY
INTEGER <return value> 0 for success and 1 for failure.
Error Conditions:
None.
Example:
Please see db_get_general_field_length (p. 627) in the MSC.Acumen, Volume 2: Code Examples.

db_get_model_file_suffix (name, suffix)

Description:
Retrieves the model file suffix associated with the named analysis code.
Input:
STRING name[31] Name of the analysis code for which the suffix is to be
retrieved.
Output:
STRING suffix[6] Location into which the named suffix is to be retrieved.
INTEGER <Return Value> Success or failure of routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
Example:
Please see db_get_model_file_suffix (p. 629) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
10
Function Descriptions

2.2 User Defined


A table is provided in the database which is reserved for use by the user. It can store arrays of
data for all types (integer,real,logical,strings). The table entries can be assigned arbitrary types (
as integer values) to allow multiple uses. The user can create, count, delete and retrieve the table
entries as needed. Each table entry is assigned a label for easy reference.

db_create_client_data (id, client_label, client_type, num_logicals, num_integers,


num_reals, num_strings, max_string_length, p_logical_data,
p_integer_data, p_real_data, p_string_data)

Description:
Creates a client defined entity in the database.
Input:
INTEGER client_label The external id of the db entity being created. if input as
”0”, the database will assign a label. if a number is input,
the database will ensure that it is not a duplicate, then
insert it.
INTEGER client_type Type of data uniquely defined by the client.
INTEGER num_logicals The number of logical data items being associated with this
entity.
INTEGER num_integers The number of integer data items being associated with this
entity.
INTEGER num_reals The number of real data items being associated with this
entity.
INTEGER num_strings The number of real data items being associated with this
entity.
INTEGER max_string_length The maximum length of any one string.
LOGICAL p_logical_data Pointer to an array of logicals.
INTEGER p_integer_data Pointer to an array of integers.
REAL p_real_data Pointer to an array of reals.
STRING p_string_data[] Pointer to an array of strings.
Output:
INTEGER id This filed receives the id of the client db entity that was just
created. this is the uniques database identifier for the entity.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000004 Duplicate entry exists in table.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Creates one record in the “xxx_client_entity” table in the database. Also, depending upon the
input data, this routine creates zero or more records in the “xxx_client_interger_data”, or
“xxx_client_logical_data”, or “xxx_client_real_data”, or
Example:
Please see db_create_client_data (p. 613) in the MSC.Acumen, Volume 2: Code Examples.
Main Index
CHAPTER 2 11
Model

db_count_client_labels_by_type ( client_type, nbr_of_labels)

Description:
Returns the number of all labels with a specified type.
Input:
INTEGER client_type Type of data uniquely defined by the client.
Output:
INTEGER nbr_of_labels The number of all labels.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000126 Label not found.
13000007 other database error.
Example:
Please see db_count_client_labels_by_type (p. 610) in the MSC.Acumen, Volume 2: Code
Examples.

db_count_general_field ( <field_id>, <count>)

Description:
This function returns the count of terms in a field. It returns an integer status of 0 on success
and 1 on failure.
Input:
INTEGER field_id The id of the field.
Output:
INTEGER count The count of term_ids in the field.
INTEGER <Return Value> 0 for success and 1 for failure.
Error Conditions:
None.
Example:
db_count_general_field (p. 612) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_client_data (id, num_logicals, num_integers, num_reals, num_strings,


max_string_length, p_logical_data, p_integer_data,
p_real_data, p_string_data)

Description:
Gets all data related to a specified client data entity from the database.
Input:
INTEGER id Id of the client entity for which data is requested.
INTEGER num_logicals Num of logical numbers for which storage has been
allocated by the calling routine.
INTEGER num_integers Num of integer numbers for which storage has been
allocated by the calling routine.
Main Index
12
Function Descriptions

INTEGER num_reals Num of real numbers for which storage has been allocated
by the calling routine.
INTEGER num_strings Num of strings for which storage has been allocated by the
calling routine.
INTEGER max_string_length Max number of characters to copy into p_string buffer.
Output:
LOGICAL p_logical_data(num Pointer to an array of logicals.
_logicals)
INTEGER p_integer_data() Pointer to an array of integers.
REAL p_real_data() Pointer to an array of reals.
STRING p_string_data[]() Pointer to an array of characters.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
DbFUBAR
DbClientEntityNotFound
DbOtherFailure
External Dependencies and Side Effects:
Accesses multiple records in the “xxx_client_integer_data”, “xxx_client_logical_data”,
“xxx_client_real_data”, “xxx_client_string_data” in the database.
Example:
Please see db_get_all_client_data (p. 616) in the MSC.Acumen, Volume 2: Code Examples.

db_get_client_data (client_label,id,client_type,num_logicals, num_integers,


num_reals, num_strings, max_string_length)

Description:
Gets a client data entity from the database by user defined label.
Input:
INTEGER client_label External id for the user defined entity.
Output:
INTEGER id Internal id for the user defined entity.
INTEGER client_type Type of data uniquely defined by the client.
INTEGER num_logicals The number of logical data items being associated with this
entity.
INTEGER num_integers The number of integer data items being associated with this
entity.
INTEGER num_reals The number of real data items being associated with this
entity.
INTEGER num_strings The number of string items being associated with this
entity.
INTEGER max_string_length The maximum length of any one string.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.

Main Index
CHAPTER 2 13
Model

Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses one record in the “xxx_client_data” table in the database.
Example:
See example for db_get_client_data (p. 618) in the MSC.Acumen, Volume 2: Code Examples.

db_get_client_id_by_label (client_label, id)

Description:
Returns client id given the label.
Input:
INTEGER client_label The client label.
Output:
INTEGER id The client id corresponding to the label.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000126 The entity specified in the query was not labeled.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses a record in the “xxx_client_entity” table.
Example:
Please see db_get_client_id_by_label (p. 620) in the MSC.Acumen, Volume 2: Code Examples.

db_get_client_labels_by_type (client_type, labels)

Description:
Returns all labels with a specified type.
Input:
INTEGER client_type Type of data uniquely defined by the client.
Output:
INTEGER labels() An array of labels.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000201 The specified client entity was not found.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses multiple records in the “xxx_client_entity” table.
Example:
Please see db_get_client_labels_by_type (p. 623) in the MSC.Acumen, Volume 2: Code
Examples.
Main Index
14
Function Descriptions

Main Index
CHAPTER 2 15
Model

db_get_client_label_by_id (id, client_label)

Description:
Returns client label given the id.
Input:
INTEGER id The client id.
Output:
INTEGER client_label The label corresponding to the id.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000201 The specified client entity was not found.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses a record in the “xxx_client_entity” table.
Example:
Please see db_get_client_label_by_id (p. 621) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_client_entity_label (label)

Description:
This function will get the value of the next available client entity label from the database. This
value should be equal to the highest value client entity label in use plus one.
Input:
none
Output:
INTEGER label Highest entity label used.
INTEGER <Return Value> This value returns the next available client entity label.
Error Conditions:
13000201 The specified client entity was not found.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Selects the largest client_entity_label from the database.
Example:
Please see db_get_next_client_entity_label (p. 630) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
16
Function Descriptions

db_delete_client_data (label)

Description:
Delete client data from the database.
Input:
INTEGER label User defined label of the data to be deleted.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000201 The specified client entity was not found.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Deletes one record in the “xxx_client_entity” table in the database, and depending on the client
data, all associated records.
Example:
Please see db_delete_client_data (p. 615) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Files
3
■ General
■ IGES and CAD Access
■ Journal and Session
■ Neutral

■ FrameMaker Files

Main Index
18
Function Descriptions

3.1 General
The following utilities are used for basic file management such as setting and determining file
and directory attributes.

file_is_directory (dirname)

Description:
To validate the given string as a valid directory.
Input:
STRING dirname[] Possible file directory.
Output:
INTEGER <Return Value> This function will return a value of 1 if the input value dirname
represents a valid directory and a value of 0 if the input value
dirname represents an invalid directory.
Example:
Please see file_is_directory (p. 634) in the MSC.Acumen, Volume 2: Code Examples.

get_current_dir (dirname)

Description:
Return the current directory.
Input:
none
Output:
STRING dirname[] Current directory.
INTEGER <Return Value> 0 if Function was successful.
Example:
Please see get_current_dir (p. 634) in the MSC.Acumen, Volume 2: Code Examples.

p3_ps_get_xm (<filename>)
t

Description:
This function returns the filename of the UG part being imported. Typically, a UG model is in a
file with ‘filename.prt’ extension. This function converts it to ‘filename-ps0001.xmt_txt’ file
which is actually imported into MSC.Patran. The filename is taken from the function
p3_ps_open_ug_v2() which is run previous to p3_ps_get_xmt() function. This is an internal
function called during the execution of the function p3_ps_open_ug_v2(). See example file for
this function.
Input:
None

Main Index
CHAPTER 3 19
Files

Output:
STRING filename[]() The filename for the file. This has an extension of xmt_txt
ARRAY format.
INTEGER <Return Value> Returns the output status of the function.
Error Conditions:
None.
Note:
The output of the function is an integer, but the status cannot be ascertained from this integer.
Example:
Please see p3_ps_get_xmt (p. 639) in the MSC.Acumen, Volume 2: Code Examples.

set_current_dir (dirname)

Description:
Set the current directory.
Input:
STRING dirname[] Current directory to set to.
Output:
INTEGER <Return Value> 0 = successful.
-1= failure.
Example:
See example for get_current_dir (p. 18). See also set_current_dir (p. 640) in the MSC.Acumen,
Volume 2: Code Examples.

utl_is_locked_file (filename)

Description:
This function will determine if the indicated file is currently locked.
Input:
STRING filename[] This value specifies the name of the file which will have its lock
status checked.
Output:
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an error.
Remarks:
The commands for locking and unlocking files are designed to control access to files shared
between two or more processes.
The file lock control functions assume that only one file at a time will be locked.
This function will always return FALSE for a file that is owned by the process in which this
function is executed.
Example:
Please see utl_is_locked_file (p. 649) in the MSC.Acumen, Volume 2: Code Examples.
Main Index
20
Function Descriptions

utl_lock_file (filename)

Description:
This function will set an advisory lock on a file.
Input:
STRING filename[] This value specifies the name of the file to lock.
Output:
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an error.
Error Conditions:
8111006 Error attempting to access %A%.
8111002 File %A% is in use by another user. Opening this database may cause
undesirable results.
8111001 Cannot lock %A%. Another file is locked.
8111003 Error while attempting to lock %A%.
Remarks:
The commands for locking and unlocking files are designed to control access to files shared
between two or more processes.
The file lock control functions assume that only one file at a time will be locked.
Example:
Please see utl_lock_file (p. 650) in the MSC.Acumen, Volume 2: Code Examples.

utl_unlock_file ()

Description:
This function will clear an advisory lock.
Input:
none
Output:
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an error.
Error Conditions:
8111004 Cannot perform file unlock. No files known to be locked.
8111005 Error while attempting to perform an unlock.
Remarks:
The commands for locking and unlocking files are designed to control access to files shared
between two or more processes.
The file lock control functions assume that only one file at a time will be locked.
Example:
Please see utl_unlock_file (p. 651) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 3 21
Files

uil_file_open.open_db ( name, newdb )

Description:
Open a database and set some initial parameters.
Input:
STRING name[] File name of database to be opened.
LOGICAL newdb This flag will execute viewport tiling on a new database so that
it will fill all space from Main Menu to Command Window.
Output:
INTEGER <Return Value> 0 if Description was successful.
Example:
Please see uil_file_open.open_db (p. 648) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
22
Function Descriptions

3.2 IGES and CAD Access


The following functions are used for IGES access from the File menu.

ugi_export_iges_v1 ( filnam, start_section, nlpos, nlknt, product_id, author, author_org,


model_units, entity_toggle_values, all_groups, ngroups,
group_ids, patran_summary, iges_summary )

Description:
Export MSC.Patran geometry to the IGES standard.
Input:
STRING filnam[] IGES file name to create.
STRING start_section[] IGES file start section prolog lines.
INTEGER nlpos ( ) Array of nlknt values. Each entry is the # of characters
for that line of the “IGES file start section prolog” plus
the pervious lines.
INTEGER nlknt Number of lines in the “IGES file start section prolog”.
STRING product_id[] Product Id for receiving system.
STRING author[] Author.
STRING author_org[] Author’s Organization
STRING model_units[] IGES file model units.
LOGICAL entity_toggle_values(35) Flags to specify which MSC.Patran entity types to
export. Only the first 7 flags are used.
LOGICAL all_groups TRUE if all groups are to be exported.
INTEGER ngroups Number of groups to export.
INTEGER group_ids ( ) Group ids to export.
Output:
INTEGER patran_summary (8) Number of MSC.Patran entities processed.
INTEGER iges_summary (21) Number of IGES entities created.
INTEGER <Return Value> 0 if Function was successful.
Example:
Please see ugi_export_iges_v1 (p. 642) in the MSC.Acumen, Volume 2: Code Examples.

ugi_import_iges_v3 (file_name, ipref142, group_name, entity_toggle_values,


color_toggle_values, color_method, color_definition, all_layers,
layer, number_of_groups, group_entity_ids, group_entity_values,
group_color_values, layer_pointers, group_levals, scale,
iges_count, patran_count)
Description:
This function imports geometry information from a file in the IGES standard file format into the
MSC.Patran database.
Input:
STRING file_name [ ] Filename and its path which is to be imported.

Main Index
CHAPTER 3 23
Files

INTEGER ipref142 User preference for curve on surface(142) entity


representation use flag.
0 = Unspecified, use what is defiened in the IGES file.
1 = S or B is preferred (Parametric space)
2 = C is preferred (Real space)
STRING group_name[] Group name in which the imported geometry is added.
LOGICAL entity_toggle_values() This value specifies the entity type filter status flags to
ARRAY specify which IGES entity types to import.
LOGICAL color_toggle_values() This value specifies the entity color filter status flags to
ARRAY specify which IGES entity colors to import.
STRING color_method[ ] This value is used to specify the color definition entity
method used to import color definition entities.
STRING color_defination[ ] This value specifies the color definition entities to import.
LOGICAL all_layers TRUE if all geometry layers are to be imported.
STRING layer[ ] This value specifies a string that is used to specify the
geometry layers to be imported.
INTEGER number_of_groups Number of groups.
INTEGER group_entity_ids ID values for each user group.
(number_of_groups)
LOGICAL group_entity_values This value specifies a 2D array that contains values set to
ARRAY (22,number_of_groups) TRUE if an entity is to be included and FALSE if an entity
is not to be included in the group being imported. The
offset in the first dimension corresponds to the group id
in the same offset of the group_entity_ids input value.
The offset in the second dimension of the array identifies
the entity type.
LOGICAL group_color_values This value specifies a 2D array that contains values set to
ARRAY (10, number_of_groups)TRUE if a color value is to be used. The offset in the first
dimension of the array corresponds to the group id in the
same offset of the group_entity_ids input value. The
offset in the second dimension of the array identifies the
color type.
INTEGER layer_pointers(number This value specifies an array that is used by setting a
ARRAY _of_groups) value at an offset that corresponds with the offset into the
group_entity_ids input value that lists the group ids. The
value at that offset in the array identifies the offset into
the group_layers input values where the number of
layers values for each group is stored.The maximum
value allowed for this array is equal to the number of
integers in the group_layers input value.
INTEGER group_layers This value specifies an array used to identify the number
of layers imported for each group. The size of this array
must be equal to or greater than the largest value placed
in the layer_pointer input value.
Output:
REAL scale This value return the IGES file model space scale.
INTEGER iges_count(50) Number of IGES entities imported by type.
ARRAY
INTEGER patran_count(8) Number of MSC.Patran entities written to the database
ARRAY by type.
Main Index
24
Function Descriptions

INTEGER <Return Value> This function returns a value 0 for success and a non-zero
value to indicate a change in status or an error.
Error Conditions:
-1 This is an internal status condition. There is no
corresponding status message in the message database.
Example:
Please see ugi_import_iges_v3 (p. 643) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 3 25
Files

3.3 Journal and Session


The following utilities are used to manage journal file and session file operations.

jou_file_write ( astring )

Description:
To write a string to the journal file ONLY.
Input:
STRING astring[] string to write.
Output:
none
Example:
Please see jou_file_write (p. 635) in the MSC.Acumen, Volume 2: Code Examples.

sf_write_disable ( alogical )

Description:
To control whether the next “$ pcl_func(blah, blah)” gets written to the session file. Depends
upon value of ’flag’.
Input:
LOGICAL alogical TRUE -- don’t record next “$ pcl_func()”.
FALSE - record next “$ pcl_func()”.
Output:
none
Example:
Please see sf_write_disable (p. 641) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
26
Function Descriptions

3.4 Neutral
The following PCL functions are used to export MSC.Patran 2.5 format neutral files. nf_write_all
will create the GFEG and CFEG tables for association between geometry in FEM. Since
MSC.Patran has no limitation on the number of nodes and elements associated to the geometry,
care should be taken when importing neutral files generated from nf_write_all into
MSC.Patran 2.5 so that the 2000 nodes per a single geometric region (Curve, surface or solid)
limit is not exceeded.

neutral_export ( pname, title, entflg, grp_all, ngroups, groudid )


2

Description:
Export data to a neutral file, applying the specified entity and group filters first.
Input:
STRING pname[] Neutral file name.
STRING title[] Neutral file title.
LOGICAL entflg(35 ) Entity filters. TRUE/FALSE toggle flags. Only 22 of the 35
values are used. Visable flags include: #1-8, #10, #11, #14-17,
#19-24, #32, and #33.
LOGICAL grp_all TRUE if ALL groups are to be output.
INTEGER ngroups The number of groups to be output.
INTEGER groudid( ) The IDs of the groups to be output.
Output:
INTEGER <Return Value> 0 if Function was successful.
Example:
Please see neutral_export2 (p. 635) in the MSC.Acumen, Volume 2: Code Examples.

nf_write ( pname, title, pfea )

Description:
Write a MSC.Patran 2.5 format neutral file from the open MSC.Patran database. Use the PFEA
translator as a base, add new Phase I. If PFEA is TRUE, write only a PFEA neutral file.
Input:
STRING pname[] Neutral file name.
STRING title[] Neutral file title.
LOGICAL pfea Flag to write only PFEA neutral file if TRUE.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
45000001 Unable to open output file. Aborting Neutral File Export.
8107002 Last command aborted.
45000002 Error writing Finite Element Model. Will try to complete Neutral File.
45000003 Error writing Named Components. Aborting FEM portion of Neutral File. Will
try to complete writing geometry, if any.
Main Index
CHAPTER 3 27
Files

Example:
Please see nf_write (p. 636) in the MSC.Acumen, Volume 2: Code Examples.

nf_write2 ( pname, title, pfea, entflg, grp_all, ngroups, groupid )

Description:
Write a MSC.Patran 2.5 format neutral file from the open MSC.Patran database. Use the PFEA
translator as a base, add new Phase I. If PFEA is TRUE, write only a PFEA neutral file.
Input:
STRING pname[] Neutral file name.
STRING title[] Neutral file title.
LOGICAL pfea Flag to write only PFEA neutral file if TRUE.
LOGICAL entflg( ) Entity filters. TRUE/FALSE toggle flags.
LOGICAL grp_all TRUE if ALL groups are to be output.
INTEGER ngroups The number of groups to be output.
INTEGER groupid( ) The IDs of the groups to be output.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
45000001 Unable to open output file. Aborting Neutral File Export.
45000002 Error writing Finite Element Model. Will try to complete Neutral File.
45000003 Error writing Named Components. Aborting FEM portion of Neutral File. Will
try to complete writing geometry, if any.
Example:
Please see nf_write2 (p. 638) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
28
Function Descriptions

3.5 FrameMaker Files


The following PCL Functions are useful for capturing graphics to be used in generation of on-
line help documents. On-line help is based on FrameMaker (tm) and the files resulting from calls
to ui_framemaker are MIF format which is recognized by FrameMaker.

ui_form_to_frame (classname, scale)

Description:
Given the string classname as the name of a class which has a form currently displayed, this
function will create a framemaker file classname.mif file which contains the form at a scale
factor of scale.
Input:
STRING classname[] Name of the PCL class containing the form to be used.
REAL scale Scale factor for translation. Optional and defaults to 1.0.
Output:
none
Comments:
Creates FrameMaker objects when imported into a FrameMaker document through the import
file menu pick.
Example:
Please see ui_form_to_frame (p. 645) in the MSC.Acumen, Volume 2: Code Examples.

ui_framemaker ( option,[scale] )

Description:
Set automatic framemaker generation. If option is 1, whenever ui_form_display() is called, the
classname is echoed to the history window. This gives you the classname in order to type a
ui_form_to_frame() command. If option is 2, then whenever ui_form_display() is called, the
name of the class is echoed, and a call is automatically made to ui_form_to_frame() with the
specified scale factor. If option is 0, then ui_form_display() reverts back to normal operation.
Input:
INTEGER option Specifies how the function works. See Description above.
REAL scale Scale factor for translation. Optional and defaults to 1.0.
Output:
none
Example:
Please see ui_framemaker (p. 646) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Graphics
4
■ General
■ Element Tables
■ Light Source
■ Color Look-up Tables

■ Deformation Plots
■ Ranges
■ Spectrums
■ Titles
■ Graphics Manager
■ Clipping Planes

Main Index
30
Function Descriptions

4.1 General
The following general purpose utilities affects or reports the state of the graphics manager.

ga_error ()

Description:
Returns a LOGICAL indicating whether the last call to the Graphics application raised an error
condition.
Input:
None.
Output:
LOGICAL <Return Value> Flag indicating if an error occurred.
Example:
Please see ga_error (p. 682) in the MSC.Acumen, Volume 2: Code Examples.

verify_boundaries_display_mgr.initialize ()

Description:
Save graphics properties associated with the current group. Used in conjunction with
verify_boundaries_display_mgr.plot/erase.
Input:
None.
Output:
None.
Example:
Please see verify_boundaries_display_mgr.initialize (p. 831) in the MSC.Acumen, Volume 2:
Code Examples.

verify_boundaries_display_mgr.plot (displ_type )

Description:
Plot the free boundaries by changing display properties.
Input:
STRING displ_type[] “Free_Edges” or “Free_Faces”
Output:
None.
Example:
Please see verify_boundaries_display_mgr.plot (p. 832) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 4 31
Graphics

verify_boundaries_display_mgr.erase ( )

Description:
Erase the free boundary display by resetting graphics properties
Input:
None.
Output:
None.
Example:
Please see verify_boundaries_display_mgr.erase (p. 831) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
32
Function Descriptions

4.2 Element Tables


The element graphics tables are used to display scalar and vector plots for imaging.

ga_elem_scalar_create ( title,nbr_elems,elem_ids,nbr_values,max_vals,scalars,id )

Description:
Creates a scalar element table.
Input:
STRING title[] Title of table.
INTEGER nbr_elems Number of elements to place in table.
INTEGER elem_ids ( ) Array of element ids.
INTEGER nbr_values ( ) Number of scalar values in each element.
INTEGER max_vals Maximum number of scalar values in any element.
REAL scalars (nbr_elems, Scalar values for all elements.
max_value)
Output:
INTEGER id Id of created element scalar table.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_elem_scalar_create (p. 679) in the MSC.Acumen, Volume 2: Code Examples.

ga_elem_scalar_single_create ( title, nbr_elems, elem_ids, nbr_nodes, scalars, id )

Description:
Creates a scalar element table given only one value per element.
Input:
STRING title[] Title of table.
INTEGER nbr_elems Number of elements to place in table.
INTEGER elem_ids ( ) Array of element ids.
INTEGER nbr_nodes ( ) Number of nodes in each element.
REAL scalars ( ) One scalar value per element.
Output:
INTEGER id Id of created element scalar table.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_elem_scalar_single_create (p. 681) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 4 33
Graphics

ga_vector_create ( title, comp_vect_flag, sym_flag, nbr_vectors, vect_ent_types,


vect_ent_ids, vect_locs, normals, vect_types, anchor_styles,
vect_colors, sub_ids, id )

Description:
Creates a vector table.
Input:
STRING title[] Title of table.
INTEGER comp_vect_flag Whether 3 component vector should be displayed or
a resultant vector.
INTEGER sym_flag Whether vector should be displayed symmetrically
on the opposite side.
INTEGER nbr_vectors Number of vectors to place in table.
INTEGER vect_ent_types ( ) Array of entity types.
INTEGER vect_ent_ids ( ) Array of entity ids (if negative, use the location to
signify the location of the vector).
REAL vect_locs (nbr_vectors ,3) Location of vector (only used if vector_ent_ids < 0 ).
REAL normals (nbr_vectors ,3) Normal of vector (includes length).
INTEGER vect_types ( ) Vector types.
0 - no arrow head.
1 - one arrow head.
2 - double head.
3 - triple head.
4 - one arrow head 0-displacements.
5 - double head 0-displacements.
6 - triple head 0-displacements.
7 - one arrow head imposed displacements.
8 - double head imposed displacements.
9 - triple head imposed displacements.
100’s are reserved for markers.
101 - dot.
102 - circle.
103 - X.
104 - +.
105 - filled circle.
106 - square.
107 - filled square.
108 - triangle.
109 - filled triangle.
110 - diamond.
111 - filled diamond.
INTEGER anchor_styles ( ) Anchor styles (1-base, 2-tip, 3-middle).

Main Index
34
Function Descriptions

INTEGER vect_colors ( ) Vector colors.


For results:
NULL - use the colors on D.P. form.
0 - use vector color.
1,2,3 - use component colors.
For functional assignments:
Values must be specified. The value is the type of
vector. The possible values are taken from the
preference include file ( LBCCOLOR1, LBCCOLOR2,
EPCOLOR1, EPCOLOR2, etc. ).
INTEGER sub_ids ( ) Sub ids. Only used by FA.
Output:
INTEGER id Id of created vector table.
Example:
Please see ga_vector_create (p. 770) in the MSC.Acumen, Volume 2: Code Examples.

ga_vector_get ( id, title, comp_vect_flag, sym_flag, vect_ent_types, vect_ent_ids,


vect_locs, normals, vect_types, anchor_styles, vect_colors, sub_ids )

Description:
Gets a vector table.
Input:
INTEGER id Id of vector table.
Output:
STRING title[] Title of table.
INTEGER comp_vect_flag Whether 3 component vector should be displayed or a
resultant vector.
INTEGER sym_flag Whether vector should be displayed symmetrically on
the opposite side.
INTEGER vect_ent_types ( ) Array of entity types.
INTEGER vect_ent_ids ( ) Array of entity ids (if negative, use the location to
signify the location of the vector).
REAL vect_locs ( ,3) Location of vector (only used if vector_ent_ids < 0 ).
REAL normals ( ,3) Normal of vector (includes length).
INTEGER vect_types ( ) Vector types (1-one arrow head, 2-double head, 3-triple
head, 0-no arrow head).
INTEGER anchor_styles ( ) Anchor styles (1-base, 2-tip, 3-middle).
INTEGER vect_colors ( ) Vector colors.
INTEGER sub_ids ( ) Sub-ids.
INTEGER <Return Value> 0 if function was succesful.
Error Conditions:
11000143 The specified vector result table was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_vector_get (p. 772) in the MSC.Acumen, Volume 2: Code Examples.
Main Index
CHAPTER 4 35
Graphics

ga_vector_number_get ( id, number )

Description:
Gets the number of vectors in vector table.
Input:
INTEGER id Id of vector table.
Output:
INTEGER number Number of vectors in table.
INTEGER <Return Value> 0 if function was successful.
Example:
Please see ga_vector_number_get (p. 775) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
36
Function Descriptions

4.3 Light Source


Manages graphic light sources.

ga_light_attenuation_get ( name, value )

Description:
Get the attenuation of the light.
Input:
STRING name[] Light source name.
Output:
REAL value Attenuation of light (0.0-1.0).
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_attenuation_get (p. 683) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_attenuation_set ( name, value )

Description:
Set the attenuation of the light.
Input:
STRING name[] Light source name.
REAL value Attenuation of light (0.0-1.0).
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_attenuation_set (p. 684) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_color_get ( name, index )

Description:
Get the light source color.
Input:
STRING name[] Light source name.

Main Index
CHAPTER 4 37
Graphics

Output:
INTEGER index Light color.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_color_get (p. 685) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_color_set ( name, index )

Description:
Set the light source color.
Input:
STRING name Light source name.
INTEGER index Light source color index.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000086 The color index for the current lookup table is out of range.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_light_attenuation_set (p. 36). See also ga_light_color_set (p. 686) in the
MSC.Acumen, Volume 2: Code Examples.

ga_light_create ( name )

Description:
Creates a light source.
Input:
STRING name Name of light source.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000036 A light source with the given name is already in the database.
11000097 There is not enough disk space to complete operation.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_create (p. 687) in the MSC.Acumen, Volume 2: Code Examples.
Main Index
38
Function Descriptions

ga_light_delete ( name )

Description:
Delete a light source.
Input:
STRING name[] Name of light source.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_delete (p. 688) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_direction_get ( name, value )

Description:
Get the light source direction.
Input:
STRING name Light source name.
Output:
REAL value (3) Direction of light source.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_direction_get (p. 689) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_direction_set ( name, value )

Description:
Set the light source direction.
Input:
STRING name[] Light source name.
REAL value (3) Direction of light source.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Main Index
CHAPTER 4 39
Graphics

Example:
See example for ga_light_attenuation_set (p. 36). See also ga_light_direction_set (p. 691) in
the MSC.Acumen, Volume 2: Code Examples.

ga_light_icon_get ( name, value )

Description:
Get the status whether the icon is displayed.
Input:
STRING name[] Light source name.
Output:
INTEGER value Flag specifying if an icon should be displayed at light
source.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_icon_get (p. 692) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_icon_set ( name, value )

Description:
Set the status whether the icon is displayed.
Input:
STRING name[] Light source name.
INTEGER value Flag specifying if an icon should be displayed at light
source.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_light_attenuation_set (p. 36). See also ga_light_icon_set (p. 693) in the
MSC.Acumen, Volume 2: Code Examples.

Main Index
40
Function Descriptions

ga_light_intensity_get ( name, value )

Description:
Get the intensity of the light.
Input:
STRING name[] Light source name.
Output:
REAL value Intensity of light (0.0-1.0).
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_intensity_get (p. 694) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_intensity_set ( name, value )

Description:
Set the intensity of the light.
Input:
STRING name[] Light source name.
REAL value Intensity of light (0.0-1.0).
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_light_attenuation_set (p. 36). See also ga_light_intensity_set (p. 695) in
the MSC.Acumen, Volume 2: Code Examples.

ga_light_lights_get ( lights_list )

Description:
Gets the list of lights.
Input:
None.
Output:
STRING lights_list [ ] ( ) List of lights.
INTEGER <Return Value> See error conditions.

Main Index
CHAPTER 4 41
Graphics

Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_lights_get (p. 696) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_location_get ( name, value )

Description:
Get the location of light source.
Input:
STRING name[] Light source name.
Output:
REAL value (3) Location of light source (x,y,z).
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_location_get (p. 697) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_location_set ( name, value )

Description:
Set the location of light source.
Input:
STRING name[] Light source name.
REAL value (3) Location of light source (x,y,z).
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_light_attenuation_set (p. 36). See also ga_light_location_set (p. 698) in
the MSC.Acumen, Volume 2: Code Examples.

Main Index
42
Function Descriptions

ga_light_movement_get ( name, value )

Description:
Get whether the light moves with the model or not.
Input:
STRING name[] Light source name.
Output:
INTEGER value Flag specifying whether light moves with the model or
not.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_movement_get (p. 699) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_movement_set ( name, value )

Description:
Set the status whether the light should move with the model.
Input:
STRING name[] Light source name.
INTEGER value Flag specifying if the light should move with the model.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_light_attenuation_set (p. 36). See also ga_light_movement_set (p. 700)
in the MSC.Acumen, Volume 2: Code Examples.

ga_light_nlights_get ( nlights )

Description:
Gets the number of lights.
Input:
None.
Output:
INTEGER nlights Number of lights.
INTEGER <Return Value> See error conditions.
Main Index
CHAPTER 4 43
Graphics

Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_nlights_get (p. 702) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_nposted_get ( nlights )

Description:
Gets the number of posted lights.
Input:
None.
Output:
INTEGER nlights Number of posted lights.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_nposted_get (p. 702) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_post ( name )

Description:
Post a light source.
Input:
STRING name[] Name of light source.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_post (p. 703) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_posted_get ( lights_list )

Description:
Gets the list of posted lights.
Input:
None.
Output:
STRING lights_list [ ] ( ) List of lights.
Main Index
44
Function Descriptions

INTEGER <Return Value> See error conditions.


Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_posted_get (p. 704) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_type_get ( name, value )

Description:
Get the light source type.
Input:
STRING name[] Light source name.
Output:
STRING value[] Type.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_type_get (p. 705) in the MSC.Acumen, Volume 2: Code Examples.

ga_light_type_set ( name, value )

Description:
Set the light source type.
Input:
STRING name[] Light source name.
STRING value[] Light source type.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_type_set (p. 706) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 45
Graphics

ga_light_unpost ( name )

Description:
Unpost a light source.
Input:
STRING name[] Name of light source.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000037 The light source name is invalid.
11000104 The specified light source was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_light_unpost (p. 707) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
46
Function Descriptions

4.4 Color Look-up Tables

ga_lookup_colors_get ( name, rgb )

Description:
Get the colors defined in LUT.
Input:
STRING name[] LUT name.
Output:
REAL rgb ( ,3) Colors in LUT.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000102 The specified lookup table was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_colors_get (p. 709) in the MSC.Acumen, Volume 2: Code Examples.

ga_lookup_colors_set ( name, offset, number, rgb )

Description:
Set the LUT’s colors.
Input:
STRING name[] LUT name.
INTEGER offset Start position.
INTEGER number Number of colors in LUT.
REAL rgb ( ,3) Triplets of RGB values.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000026 The lookup table is invalid.
11000028 An incorrect offset was specified in lookup table.
11000027 An incorrect number of colors was specified for lookup table.
11000102 The specified lookup table was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_colors_set (p. 710) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 47
Graphics

ga_lookup_create ( name, number, rgb )

Description:
Create a lookup table.
Input:
STRING name[] LUT name.
INTEGER number Number of colors in LUT.
REAL rgb ( ,3) Triplets of RGB values.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000026 The lookup table is invalid.
11000027 An incorrect number of colors was specified for lookup table.
11000097 There is not enough disk space to complete operation.
11000025 A lookup table with the given name is already in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_create (p. 712) in the MSC.Acumen, Volume 2: Code Examples.

ga_lookup_current_get ( name )

Description:
Get the current LUT.
Input:
None.
Output:
STRING name[] LUT name.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000102 The specified lookup table was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_current_get (p. 713) in the MSC.Acumen, Volume 2: Code Examples.

ga_lookup_current_set ( name )

Description:
Set the current LUT.
Input:
STRING name[] LUT name.
Output:
INTEGER <Return Value> See error conditions.

Main Index
48
Function Descriptions

Error Conditions:
11000026 The lookup table is invalid.
11000102 The specified lookup table was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_current_set (p. 714) in the MSC.Acumen, Volume 2: Code Examples.

ga_lookup_delete ( name )

Description:
Delete a LUT.
Input:
STRING name[] Display name.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000026 The lookup table is invalid.
11000102 The specified lookup table was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_delete (p. 715) in the MSC.Acumen, Volume 2: Code Examples.

ga_lookup_ncolors_get ( name, number )

Description:
Get the number of colors defined in LUT.
Input:
STRING name[] LUT name.
Output:
INTEGER number Number of colors.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000026 The lookup table is invalid.
11000102 The specified lookup table was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_ncolors_get (p. 716) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 49
Graphics

ga_lookup_ntables_get ( ntables )

Description:
Get the number of luts in database.
Input:
None.
Output:
INTEGER ntables Number of luts.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000102 The specified lookup table was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_ntables_get (p. 717) in the MSC.Acumen, Volume 2: Code Examples.

ga_lookup_rename ( old_name, new_name )

Description:
Rename a LUT.
Input:
STRING old_name[] Old LUT name.
STRING new_name[] New LUT name.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000026 The lookup table is invalid.
11000102 The specified lookup table was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_rename (p. 718) in the MSC.Acumen, Volume 2: Code Examples.

ga_lookup_tables_get ( ntables )

Description:
Get the list of luts in database.
Input:
None.
Output:
STRING ntables [ ] ( ) List of lut names.
INTEGER <Return Value> See error conditions.

Main Index
50
Function Descriptions

Error Conditions:
11000102 The specified lookup table was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_lookup_tables_get (p. 719) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 51
Graphics

4.5 Deformation Plots


The following function are useful for managing deformation plots.

ga_node_deform_create ( title, nbr_nodes, node_ids, deforms, id )

Description:
Creates a node deformation table.
Input:
STRING title[] Title of table.
INTEGER nbr_nodes Number of nodes to place in table.
INTEGER node_ids ( ) Array of node ids.
REAL deforms (nbr_nodes,3) Deform values for all nodes.
Output:
INTEGER id Id of created node deformation table.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_node_deform_create (p. 720) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
52
Function Descriptions

4.6 Ranges

ga_range_contour_get ( name, flag )

Description:
Get whether range is to be displayed using contour values.
Input:
STRING name[] Range name.
Output:
INTEGER flag Flag=1 if contour values are displayed, Flag=0 if fringe
values.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_contour_get (p. 721) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_contour_set ( name, flag )

Description:
Set the display type flag.
Input:
STRING name[] Name of range.
INTEGER flag Flag=1 if contour values are displayed
Flag=0 if fringe values.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_contour_set (p. 722) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_create ( name, number )

Description:
Creates a range.
Input:
STRING name[] Name of range.
Main Index
CHAPTER 4 53
Graphics

INTEGER number Number of sub-ranges in range.


Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000133 A range with the given name is already in the database.
11000097 There is not enough disk space to complete operation.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_create (p. 724) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_delete ( name )

Description:
Delete a range
Input:
STRING name[] Name of range.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_delete (p. 726) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_exist_get ( name, flag )

Description:
Check if range exists.
Input:
STRING name[] Range name.
Output:
INTEGER flag Exist flag.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
Example:
See example for ga_range_create (p. 52). See also ga_range_exist_get (p. 728) in the
MSC.Acumen, Volume 2: Code Examples.

Main Index
54
Function Descriptions

ga_range_nranges_get ( nranges )

Description:
Gets the number of ranges.
Input:
None.
Output:
INTEGER nranges Number of ranges.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_nranges_get (p. 729) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_nvalues_get ( name, number )

Description:
Get the number of sub-ranges defined in range.
Input:
STRING name[] Range name.
Output:
INTEGER number Number of sub-ranges.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_nvalues_get (p. 729) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_ranges_get ( ranges )

Description:
Gets the list of ranges.
Input:
None.
Output:
STRING ranges [ ] ( ) List of ranges.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_ranges_get (p. 730) in the MSC.Acumen, Volume 2: Code Examples.
Main Index
CHAPTER 4 55
Graphics

ga_range_rename ( old, new )

Description:
Rename a range.
Input:
STRING old[] Current name of range.
STRING new[] New name of range.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_rename (p. 731) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_startend_set ( name, start, end )

Description:
Set the sub-ranges in range given start/end.
Input:
STRING name[] Name of range.
REAL start Start value.
REAL end End value.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_startend_set (p. 733) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_threshold_set ( name, start, end, sthresh_fl, sthresh, ethresh_fl, ethresh )

Description:
Set the sub-ranges in range given start/end and threshold values.
Input:
STRING name[] Name of range.
REAL start Start value.
REAL end End value.
INTEGER sthresh_fl Whether a starting threshold value is spec.
REAL sthresh Starting threshold value.
Main Index
56
Function Descriptions

INTEGER ethresh_fl Whether an ending threshold value is spec.


REAL ethresh Ending threshold value.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_threshold_set (p. 735) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_values_get ( name, from, to, middle )

Description:
Get the sub-ranges defined in range.
Input:
STRING name[] Range name.
Output:
REAL from ( ) From values.
REAL to ( ) To values.
REAL ranges [ ] ( ) List of ranges.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_values_get (p. 737) in the MSC.Acumen, Volume 2: Code Examples.

ga_range_values_set ( name, from, to, middle )

Description:
Set the sub-ranges in range.
Input:
STRING name[] Name of range.
REAL from ( ) From values.
REAL to ( ) To values.
REAL middle ( ) Middle values.
Output:
INTEGER <Return Value> See error conditions.

Main Index
CHAPTER 4 57
Graphics

Error Conditions:
11000134 The range name is invalid.
11000136 The specified range was not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_range_values_set (p. 738) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
58
Function Descriptions

4.7 Spectrums

ga_spectrum_colors_get ( name, colors )

Description:
Get the colors defined in a spectrum.
Input:
STRING name[] Spectrum name.
Output:
INTEGER colors ( ) Color index values.
INTEGER <Return Value> GA error status.
Error Conditions:
11000030 The spectrum name is invalid.
11000106 The specified spectrum was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_colors_get (p. 740) in the MSC.Acumen, Volume 2: Code Examples.

ga_spectrum_colors_set ( name, offset, number, colors )

Description:
Set the colors in spectrum.
Input:
STRING name[] Name of spectrum.
INTEGER offset Starting position in color table where colors should be
modified.
INTEGER number Number of colors in spectrum.
INTEGER colors ( ) Color values.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000030 The spectrum name is invalid.
11000032 An incorrect offset was specified in spectrum color table.
11000031 An incorrect number of colors was specified for the spectrum.
11000106 The specified spectrum was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_colors_set (p. 741) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 59
Graphics

ga_spectrum_continuous_get ( name, value )

Description:
Get the continuous tone flag.
Input:
STRING name[] Spectrum name.
Output:
INTEGER value Continuous tone flag.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000030 The spectrum name is invalid.
11000106 The specified spectrum was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_continuous_get (p. 743) in the MSC.Acumen, Volume 2: Code
Examples.

ga_spectrum_continuous_set ( name, value )

Description:
Set the continuous tone flag.
Input:
STRING name[] Spectrum name.
INTEGER value Continuous tone flag.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000030 The spectrum name is invalid.
11000106 The specified spectrum was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_spectrum_colors_set (p. 58). See also ga_spectrum_continuous_set
(p. 744) in the MSC.Acumen, Volume 2: Code Examples.

ga_spectrum_create ( name, number, colors )

Description:
Creates a spectrum color table.
Input:
STRING name[] Name of spectrum table.
INTEGER number Number of colors in spectrum.
INTEGER colors ( ) Color index values.

Main Index
60
Function Descriptions

Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000030 The spectrum name is invalid.
11000031 An incorrect number of colors was specified for the spectrum.
11000029 A spectrum with the given name is already in the database.
11000097 There is not enough disk space to complete operation.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_create (p. 745) in the MSC.Acumen, Volume 2: Code Examples.

ga_spectrum_current_get ( name )

Description:
Gets the current spectrum.
Input:
None.
Output:
STRING name[] Spectrum name.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000030 The spectrum name is invalid.
11000106 The specified spectrum was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_current_get (p. 747) in the MSC.Acumen, Volume 2: Code Examples.

ga_spectrum_current_set ( name )

Description:
Sets the current spectrum.
Input:
STRING name[] Spectrum name.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000030 The spectrum name is invalid.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_current_set (p. 747) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 61
Graphics

ga_spectrum_delete ( name )

Description:
Delete a spectrum table.
Input:
STRING name[] Name of spectrum table.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000030 The spectrum name is invalid.
11000106 The specified spectrum was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_delete (p. 749) in the MSC.Acumen, Volume 2: Code Examples.

ga_spectrum_interpolation_get ( name, factor )

Description:
Get the interpolation factor.
Input:
STRING name[] Spectrum name.
Output:
REAL factor Interpolation factor.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000030 The spectrum name is invalid.
11000106 The specified spectrum was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_interpolation_get (p. 750) in the MSC.Acumen, Volume 2: Code
Examples.

ga_spectrum_interpolation_set ( name, factor )

Description:
Set the interpolation factor.
Input:
STRING name[] Spectrum name.
REAL factor Interpolation factor.
Output:
INTEGER <Return Value> See error conditions.

Main Index
62
Function Descriptions

Error Conditions:
11000030 The spectrum name is invalid.
11000033 An incorrect interpolation factor was specified.
11000106 The specified spectrum was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_spectrum_colors_set (p. 58). See also ga_spectrum_interpolation_set
(p. 751) in the MSC.Acumen, Volume 2: Code Examples.

ga_spectrum_ncolors_get ( name, number )

Description:
Get the number of colors defined in spectrum.
Input:
STRING name[] Spectrum name.
Output:
INTEGER number Number of colors.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000030 The spectrum name is invalid.
11000106 The specified spectrum was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_ncolors_get (p. 753) in the MSC.Acumen, Volume 2: Code Examples.

ga_spectrum_nspectrums_get ( nspectrums )

Description:
Gets the number of spectrums.
Input:
None.
Output:
INTEGER nspectrums Number of spectrums.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_nspectrums_get (p. 753) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 4 63
Graphics

ga_spectrum_rename ( old, new )

Description:
Rename a spectrum.
Input:
STRING old[] Current name of spectrum.
STRING new[] New name of spectrum.
Output:
INTEGER <Return Value> GA Error status
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_rename (p. 754) in the MSC.Acumen, Volume 2: Code Examples.

ga_spectrum_spectrums_get ( spectrums )

Description:
Gets the list of spectrums.
Input:
None.
Output:
STRING spectrums [ ] ( ) List of spectrums.
INTEGER <Return Value> GA error status.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_spectrum_spectrums_get (p. 755) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
64
Function Descriptions

4.8 Titles

ga_title_color_get ( old_name, size )

Description:
Get the color.
Input:
STRING old_name[] Title name.
Output:
INTEGER size Color.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000152 Invalid title name.
11000151 Title not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_color_get (p. 756) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_color_set ( old_name, size )

Description:
Set the color.
Input:
STRING old_name[] Title name.
INTEGER size Title color.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000152 Invalid title name.
11000151 Title not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_color_set (p. 757) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_create ( name, x, y, color, size )

Description:
Creates title.
Input:
STRING name[] Title.
REAL x X percentage.
REAL y Y percentage.
Main Index
CHAPTER 4 65
Graphics

INTEGER color Text color.


INTEGER size Font size.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000150 Duplicate title.
11000097 There is not enough disk space to complete operation.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_create (p. 759) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_delete ( name )

Description:
Delete title.
Input:
STRING name[] Title.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000150 Duplicate title.
11000097 There is not enough disk space to complete operation.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_delete (p. 760) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_font_size_get ( old_name, size )

Description:
Get the font size.
Input:
STRING old_name[] Title name.
Output:
INTEGER size Font size.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000152 Invalid title name.
11000151 Title not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_font_size_get (p. 761) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
66
Function Descriptions

ga_title_font_size_set ( old_name, size )

Description:
Set the font size.
Input:
STRING old_name[] Title name.
INTEGER size Font size.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000152 Invalid title name.
11000151 Title not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_font_size_set (p. 762) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_list_get ( list )

Description:
Get the list of titles.
Input:
None.
Output:
STRING list [ ] ( ) List of titles from db.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_list_get (p. 763) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_loc_get ( old_name, x, y )

Description:
Get the x,y location.
Input:
STRING old_name[] Title name.
Output:
REAL x X percentage.
REAL y Y percentage.
INTEGER <Return Value> See error conditions.

Main Index
CHAPTER 4 67
Graphics

Error Conditions:
11000152 Invalid title name.
11000151 Title not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_loc_get (p. 764) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_loc_set ( old_name, x, y )

Description:
Set the x, y location.
Input:
STRING old_name[] Title name.
REAL x X percentage.
REAL y Y percentage.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000152 Invalid title name.
11000151 Title not found.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_loc_set (p. 765) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_nposted_get ( num )

Description:
Get the number of posted titles in db.
Input:
None.
Output:
INTEGER num Number of posted titles.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_nposted_get (p. 766) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
68
Function Descriptions

ga_title_num_get ( num )

Description:
Get the number of titles in db.
Input:
None.
Output:
INTEGER num Number of titles.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_num_get (p. 767) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_posted_get ( list )

Description:
Get the list of posted titles
Input:
None.
Output:
STRING list [ ] ( ) List of posted titles from db.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_posted_get (p. 768) in the MSC.Acumen, Volume 2: Code Examples.

ga_title_rename ( old_name, new_name )

Description:
Rename title.
Input:
STRING old_name[] Title.
STRING new_name[] Title.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_title_rename (p. 769) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 69
Graphics

4.9 Graphics Manager


The following functions are useful to manage graphics.

db_get_current_viewport_id (id)

Description:
Retrieves the viewport id associated with the specified viewport.
Input:
None.
Output:
INTEGER id Location for returned value.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
Example:
Please see db_get_current_viewport_id (p. 657) in the MSC.Acumen, Volume 2: Code Examples.

ga_view_normal_get (viewport, vector)

Description:
This function gets the view vector for the view.
Input:
STRING viewport[ ] The name of the viewport. ““ for the current viewport.
Output:
REAL ARRAYvector(3) The three values of the view vector.
INTEGER <Return_value>This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see ga_view_normal_get (p. 777) in the MSC.Acumen, Volume 2: Code Examples.

gm_convert_name ( orig_name, new_name )

Description:
This function will remove the directory from a full path and file name specification.
Input:
STRING orig_name[] This value specifies the full path and file name.
Output:
STRING new_name[] This value will return the file name from the path and
file name specification.
Main Index
70
Function Descriptions

INTEGER <Return Value> This return value is unused.


Comments:
Device dependent routine.
Example:
Please see gm_convert_name (p. 779) in the MSC.Acumen, Volume 2: Code Examples.

gm_conv_device_to_subject ( vp_id, dev_pt, sub_pt )

Description:
To convert from device space to subject space.
Input:
INTEGER vp_id Viewport id.
INTEGER dev_pt (2) Point in device space.
Output:
REAL sub_pt (3) Point in subject space.
INTEGER <Return Value> See error conditions.
Error Conditions:
15000028 The viewport must be posted to carry out this operation.
15000025 An error occurred during an operation on the graphics manager display list.
Example:
Please see gm_conv_device_to_subject (p. 778) in the MSC.Acumen, Volume 2: Code Examples.

gm_database_current ( dbname )

Description:
Get the current database from the graphics manager.
Input:
None.
Output:
STRING dbname[] Current database name.
INTEGER <Return Value> GM Error status.
Example:
Please see gm_database_current (p. 780) in the MSC.Acumen, Volume 2: Code Examples.

gm_draw_entity (segment_id, color_id, entity_type, entity_id)

Description:
This function draws an entity in segment or current viewport.
Input:
INTEGER segment_id Segment id number. If <0 then use current viewport.
INTEGER color_id Selected color id of entity.
INTEGER entity_type Type of entity, i.e. curve or surface.
INTEGER entity_id Entity ID
Main Index
CHAPTER 4 71
Graphics

Output:
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Condition:
None
Example:
Please see gm_draw_entity (p. 780) in the MSC.Acumen, Volume 2: Code Examples.

gm_fit_view ( flag )

Description:
Make sure limits are up to date and perform a fit view.
Input:
INTEGER flag If TRUE perform fit view no matter what. If FALSE, only
fit view if gm has detected that a fit is necessary.
Output:
INTEGER <Return Value> 1 if a fit view was done, 0 if not.
Example:
Please see gm_fit_view (p. 781) in the MSC.Acumen, Volume 2: Code Examples.

gm_fullcolor_mode ( )

Description:
Return whether or not the device is Fullcolor.
Input:
None.
Output:
LOGICAL <Return Value> Fullcolor status of device.
Example:
Please see gm_fullcolor_mode (p. 782) in the MSC.Acumen, Volume 2: Code Examples.

gm_graphics_off ( )

Description:
Shut down the graphics. Database will be closed and all colors freed.
Input:
None.
Output:
INTEGER <Return Value> GM Error status.
Example:
Please see gm_graphics_off (p. 783) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
72
Function Descriptions

gm_graphics_on ( )

Description:
Start the graphics back up. Called after a GmGraphicsOff call. Loads in the last database,
allocated colors.
Input:
None.
Output:
INTEGER <Return Value> GM Error status.
Example:
Please see gm_graphics_on (p. 783) in the MSC.Acumen, Volume 2: Code Examples.

gm_hilight_clear ( )

Description:
To unhighlight all of the highlighted objects.
Input:
None.
Output:
INTEGER <Return Value> GM Error status.
Example:
Please see gm_hilight_clear (p. 784) in the MSC.Acumen, Volume 2: Code Examples.

gm_hilight_entity ( type, id, color )

Description:
To highlight an entity.
Input:
INTEGER type Entity type.
INTEGER id Entity id.
INTEGER color Color to hilight. 0 - unhilight, -1 - hilight using
preference color.
Output:
INTEGER <Return Value> This return value is unused.
Error Conditions:
15000035 A new pick list could not be created.
Example:
Please see gm_hilight_entity (p. 785) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 73
Graphics

gm_hilight_string (string, color)

Description:
This function highlights all of the entities in the picklist string.
Input:
STRING string[] Picklist string.
INTEGER color Color to hilight. 0 - unhilight, -1 - hilight using preference
color.
Output:
INTEGER <Return Value> This return value is unused.
Error Condition:
None
Example:
Please see gm_hilight_string (p. 786) in the MSC.Acumen, Volume 2: Code Examples.

gm_hilight_widget ( wid_id, color )

Description:
To hilight all of the entities in the select databox.
Input:
WIDGET wid_id Select databox widget id.
INTEGER color Color to hilight. 0 - unhilight, -1 - hilight using
preference color.
Output:
INTEGER <Return Value> This return value is unused.
Error Conditions:
15000035 A new pick list could not be created.
Example:
Please see gm_hilight_widget (p. 787) in the MSC.Acumen, Volume 2: Code Examples.

gm_lookup_write ( start, ncolors, colors )

Description:
Write colors to lookup table.
Input:
INTEGER start Starting location in colormap to write to.
INTEGER ncolors Number of colors to write.
REAL colors (ncolors,3) Array of RGB values.
Output:
INTEGER <Return Value> See error conditions.
Comments:
The color table is organized in three regions; The first region is for the DAKAR color table, the
second for UIMS colors, the third for shading. When calling this routine, the ncolors should not
cross over these boundaries.
Main Index
74
Function Descriptions

Error Conditions:
15000041 User Interface colors not allocated. The colormap is being used.
15000042 Not enough colors were allocated for shading.
Example:
Please see gm_lookup_write (p. 788) in the MSC.Acumen, Volume 2: Code Examples.

gm_mpeg_pause_recording ()

Description:
This function pauses the recording of mpeg images file. This is a void function so there are no
input/output arguments in this function.
Input:
None
Output:
None
Example:
Please see gm_mpeg_pause_recording (p. 789) in the MSC.Acumen, Volume 2: Code Examples.

gm_mpeg_resume_recording ()

Description:
This function resumes the recording of mpeg images file. This is a void function so there are
no input/output arguments in this function.
Input:
None
Output:
None
Example:
Please see gm_mpeg_resume_recording (p. 791) in the MSC.Acumen, Volume 2: Code
Examples.

gm_mpeg_start_recording (file_name, file_version, x, y, width, height, quality,


maxframes)
Description:
This function starts the recording of an mpeg images file.
Input:
STRING file_name[] Recorded .mpeg filename
STRING file_version[] File version, i.e. overwrite or increment
REAL x X point coordinate
REAL y Y point coordinate
REAL width Width of the drawable area
REAL height Height of the drawable area
INTEGER quality Quality (0-100)
INTEGER maxframes Maximum number of frames.
Main Index
CHAPTER 4 75
Graphics

Output:
INTEGER <Return Value> 0 for success of the function and integer value 1 to 7 for
the failure of the function.
Error Condition:
None
Example:
Please see gm_mpeg_start_recording (p. 793) in the MSC.Acumen, Volume 2: Code Examples.

gm_mpeg_stop_recording ()

Description:
This function stops the recording of an mpeg images file. This is a void function so there are no
input/output arguments in this function.
Input:
None
Output:
None
Example:
Please see gm_mpeg_stop_recording (p. 795) in the MSC.Acumen, Volume 2: Code Examples.

gm_viewport_hardware_mode_get ( hard_flag )

Description:
To get whether viewport is drawn in hardware mode.
Input:
None.
Output:
INTEGER hard_flag If TRUE, viewport is drawn in hardware.
INTEGER <Return Value> This return value is unused.
Example:
Please see gm_viewport_hardware_mode_get (p. 797) in the MSC.Acumen, Volume 2: Code
Examples.

gm_viewport_hardware_mode_set ( hard_flag )

Description:
To set whether viewport is drawn in hardware mode.
Input:
INTEGER hard_flag If TRUE, viewport is drawn in hardware.
Output:
INTEGER <Return Value> This return value is unused.

Main Index
76
Function Descriptions

Example:
Please see gm_viewport_hardware_mode_set (p. 797) in the MSC.Acumen, Volume 2: Code
Examples.

gm_viewport_id_to_name ( id, name )

Description:
Convert from Viewport id to Viewport name.
Input:
INTEGER id Viewport ID.
Output:
STRING name[] Viewport name.
INTEGER <Return Value> GM error status.
Example:
Please see gm_viewport_id_to_name (p. 798) in the MSC.Acumen, Volume 2: Code Examples.

gm_viewport_limits_get ( persp, limits )

Description:
Determine the limits of the model in View Space.
Input:
LOGICAL persp If TRUE, this skips perspective. If FALSE, the
perspective setting in the current viewport will be used.
Output:
REAL limits (6) Min/max x, y and z coordinates of the model in View
Space.
INTEGER <Return Value> See error conditions.
Error Conditions:
15000025 An error occurred during an operation on the graphics manager display list.
15000028 The viewport must be posted to carry out this operation.
Example:
Please see gm_viewport_limits_get (p. 799) in the MSC.Acumen, Volume 2: Code Examples.

gm_viewport_ncolors_get ( ncolors )

Description:
To get the number of colors used by the GM.
Input:
None.
Output:
INTEGER ncolors Number of colors.
INTEGER <Return Value> This return value is unused.
Main Index
CHAPTER 4 77
Graphics

Example:
Please see gm_viewport_ncolors_get (p. 800) in the MSC.Acumen, Volume 2: Code Examples.

gm_viewport_refresh_off ( )

Description:
Turn off viewport refresh.
Input:
None.
Output:
INTEGER <Return Value> This return value is unused.
Example:
Please see gm_viewport_refresh_off (p. 800) in the MSC.Acumen, Volume 2: Code Examples.

gm_viewport_refresh_on ( )

Description:
Turn on viewport refresh.
Input:
None.
Output:
INTEGER <Return Value> This return value is unused.
Example:
Please see gm_viewport_refresh_on (p. 801) in the MSC.Acumen, Volume 2: Code Examples.

gm_viewport_refresh_status ( )

Description:
Return the current status of gmRefreshViewports.
Input:
None.
Output:
LOGICAL <Return Value> GM error status.
Example:
Please see gm_viewport_refresh_status (p. 802) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
78
Function Descriptions

gm_viewport_view_corners ( id, corn1, corn2, cent_x, cent_y, zoom )

Description:
Calculate the center and zoom for a viewport given two corners of a rectangle.
Input:
INTEGER id Viewport id.
INTEGER corn1[2] This value specifies the X and Y coordinates of the upper
left corner of the rectangle defining the new center point
and zoom value for the viewport.
INTEGER corn1[2] This value specifies the X and Y coordinates of the
lower right corner of the rectangle defining the new
center point and zoom value for the viewport.
Output:
REAL cent_x New center in x.
REAL cent_y New center in y.
REAL zoom New zoom.
INTEGER <Return Value> GM error status.
Example:
See example for gm_viewport_id_to_name (p. 76). See also gm_viewport_view_corners
(p. 802) in the MSC.Acumen, Volume 2: Code Examples.

gm_visibility_all ( vstat )

Description:
To set the visibility status of all objects.
Input:
LOGICAL vstat TRUE - plot.
FALSE - erase.
Output:
INTEGER <Return Value> GM error status.
Example:
Please see gm_visibility_all (p. 804) in the MSC.Acumen, Volume 2: Code Examples.

gm_visibility_widget ( entityList, visibility )

Description:
To set the visibility status of all the entities in the selectdatabox.
Input:
STRING entityList List of entities to plot or erase.
LOGICAL visibility Visibility status: TRUE - visible, FALSE - hidden.
Output:
INTEGER <Return Value> See error conditions.

Main Index
CHAPTER 4 79
Graphics

Error Conditions:
15000035 A new pick list could not be created.
Example:
Please see gm_visibility_widget (p. 804) in the MSC.Acumen, Volume 2: Code Examples.

end_vrml_animation ()

Description:
The function ends the process of copying the animation from the screen into a VRML file. This
function has to follow the start_vrml_animation() function after specifying the animation
attributes. The function has no return conditions.
Input:
None
Output:
None
Error Conditions:
None.
Example:
Please see end_vrml_animation (p. 657) in the MSC.Acumen, Volume 2: Code Examples.

gm_write_image ( <image_type >, <filename>, <version_logic>, <xpcnt >, <ypcnt>,


<width_pcnt>, <height_pcnt>, <quality>, <xyplot>)

Description:
The function prepares an image file of the specified type of the current viewport. It returns an
integer status of 0 on success and 1 on failure.
Input:
STRING image_type[] The typeof the image file – BMP, JPEG, PNG, TIFF, VRML.
STRING filename[] The name of the file to write the image with the file
extensions - bmp, jpg, png, tif, wrl.
STRING version_logic[] String to specify the version logic for writing the image file
– “Overwrite”, “Increment”. Any other string defaults to
“Increment”.
REAL xpcnt The starting percentage of the viewport for the image file in
the horizontal direction.
REAL ypcnt The starting percentage of the viewport for the image file in
the vertical direction.
REAL width_pcnt The ending percentage of the viewport for the image file in
the horizontal direction.
REAL height_pcnt The ending percentage of the viewport for the image file in
the vertical direction.
INTEGER quality An integer specifying the quality of image.
STRING xyplot The image captured will be of the current XY PLOT
window as opposed to the model graphics viewport.
Output:
Main Index
80
Function Descriptions

INTEGER <Return Value> 0 for success and 1 for failure.


Error Conditions:
None.
Example:
Please see gm_write_image (p. 805) in the MSC.Acumen, Volume 2: Code Examples.

gm_write_vrml (<filename>, <version_logic>)

Description:
The function prepares an image file of the entire viewport with the extension .wrl. It returns an
integer status of 1 on success and 0 on failure.
Input:
STRING filename[] The name of the file to write the image with the file
extension - .wrl.
STRING version_logic[] String to specify the version logic for writing the image file.
– “Overwrite”, “Increment”. Any other string defaults to
“Increment”.
Output:
INTEGER <Return Value> 1 for success and 0 for failure.
Error Conditions:
None.
Example:
Please see gm_write_vrml (p. 807) in the MSC.Acumen, Volume 2: Code Examples.

start_vrml_animation (<filename>, <version_logic>)

Description:
The function starts the process of copying the animation from the screen into a VRML file. This
function has to be followed by the end_vrml_animation() function after specifying the
animation attributes. During the course of execution of this function, the animation is sent to
the .wrl file and is not viewed in the current viewport. The function has no return conditions.
Input:
STRING filename[] The name of the file to write the animation file with the file
extension - .wrl
STRING version_logic[] String to specify the version logic for writing the image file
– “Overwrite”, “Increment”. Any other string defaults to
“Increment”.
Output:
None
Error Conditions:
None.
Example:
Please see start_vrml_animation (p. 828) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 81
Graphics

4.10 Clipping Planes

ga_clip_plane_clip_planes_get ( aclips_list )

Description:
Gets the list of arb clipping planes.
Input:
None.
Output:
STRING aclips_list [ ] List of arb clipping planes.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_clip_planes_get (p. 660) in the MSC.Acumen, Volume 2: Code
Examples.

ga_clip_plane_create ( name )

Description:
Creates an arb clipping plane.
Input:
STRING name[] Name of plane.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000154 An arbitrary clipping plane with the given name is already in the database.
11000097 There is not enough disk space to complete operation.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_create (p. 661) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_delete ( name )

Description:
Delete a plane.
Input:
STRING name[] Name of plane.
Output:
INTEGER <Return Value> See error conditions.

Main Index
82
Function Descriptions

Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_delete (p. 662) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_direction_get ( name, value )

Description:
Get the arb clipping plane direction.
Input:
STRING name[] Arb clipping plane name.
Output:
REAL value (3) Direction of arb clipping plane.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_direction_get (p. 663) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_direction_set ( name, value, up_flag )

Description:
Set the arb clipping plane direction.
Input:
STRING name[] Arb clipping plane name.
REAL value (3) Direction of arb clipping plane.
LOGICAL up_flag Calculate up vector or not.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_direction_set (p. 664) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 4 83
Graphics

ga_clip_plane_icon_get ( name, value )

Description:
Get the status whether the icon is displayed.
Input:
STRING name[] Arb clipping plane name.
Output:
INTEGER value Flag specifying if an icon should be displayed at arb
clipping plane.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_icon_get (p. 665) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_icon_set ( name, value )

Description:
Set the status whether the icon is displayed.
Input:
STRING name[] Arb clipping plane name.
INTEGER value Up of arb clipping plane.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_clip_plane_direction_set (p. 82). See also ga_clip_plane_icon_set
(p. 666) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_location_get ( name, value )

Description:
Get the location of arb clipping plane.
Input:
STRING name[] Arb clipping plane name.
Output:
REAL value (3) Location of arb clipping plane (x, y, z).
INTEGER <Return Value> See error conditions.
Main Index
84
Function Descriptions

Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_location_get (p. 667) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_location_set ( name, value )

Description:
Set the location of arb clipping plane.
Input:
STRING name Arb clipping plane name.
REAL value (3) Location of arb clipping plane (x, y, z).
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_clip_plane_direction_set (p. 82). See also ga_clip_plane_location_set
(p. 668) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_movement_get ( name, value )

Description:
Get whether the arb clipping plane moves with the model or not.
Input:
STRING name[] Arb clipping plane name.
Output:
INTEGER value (3) Flag specifying whether arb clipping plane moves with
the model or not.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_movement_get (p. 669) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 4 85
Graphics

ga_clip_plane_movement_set ( name, value )

Description:
Set the status whether the arb clipping plane should move with the model.
Input:
STRING name[] Arb clipping plane name.
INTEGER value Flag specifying if the arb clipping plane should move
with the model.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
See example for ga_clip_plane_direction_set (p. 82). See also
ga_clip_plane_movement_set (p. 671) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_nclip_planes_get ( naclips )

Description:
Gets the number of arb clipping planes.
Input:
None.
Output:
INTEGER naclips Number of arb clipping planes.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_nclip_planes_get (p. 672) in the MSC.Acumen, Volume 2: Code
Examples.

ga_clip_plane_nposted_get ( naclips )

Description:
Gets the number of posted arb clipping planes.
Input:
None.
Output:
INTEGER naclips Number of posted arb clipping planes.
INTEGER <Return Value> See error conditions.

Main Index
86
Function Descriptions

Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_nposted_get (p. 673) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_post ( name )

Description:
Post a plane.
Input:
STRING name[] Name of plane.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_post (p. 674) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_posted_get ( aclips_list )

Description:
Gets the list of posted arb clipping planes.
Input:
None.
Output:
STRING aclips_list [ ] ( ) List of arb clipping planes.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_posted_get (p. 675) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_unpost ( name )

Description:
Unpost a plane.
Input:
STRING name[] Name of plane.
Output:
INTEGER <Return Value> See error conditions.
Main Index
CHAPTER 4 87
Graphics

Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_unpost (p. 677) in the MSC.Acumen, Volume 2: Code Examples.

ga_clip_plane_up_set ( name, value )

Description:
Set the arb clipping plane Up.
Input:
STRING name[] Arb clipping plane name.
REAL value (3) Up of arb clipping plane.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000155 The arbitrary clipping plane name is invalid.
11000158 The specified arbitrary clipping plane was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_clip_plane_up_set (p. 678) in the MSC.Acumen, Volume 2: Code Examples.

clip_plane_ar_calc ( name, rx, ry, rz, new_dir, new_up )

Description:
Update the indicated clipping plane’s data to reflect the axes relative rotations about the x, y
and z axes.
Input:
STRING name[] Name of clipping plane.
REAL rx Rotation about the x-axis.
REAL ry Rotation about the y-axis.
REAL rz Rotation about the z-axis.
Output:
REAL new_dir(3) New dir.
REAL new_up(3) New up.
INTEGER <Return Value> Error status.
Example:
Please see clip_plane_ar_calc (p. 654) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
88
Function Descriptions

clip_plane_zoom_calc ( name, factor, new_loc )

Description:
Update the indicated clipping plane’s location point to reflect the zoom ( not in db ).
Input:
STRING name[] Name of clipping plane.
REAL factor Factor.
Output:
REAL new_loc(3) New location.
INTEGER <Return Value> Error status.
Example:
Please see clip_plane_zoom_calc (p. 655) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
User Interface
5
■ Error Message Handling
■ List Processor
■ General
■ Widgets

■ Help

Main Index
90
Function Descriptions

5.1 Error Message Handling


A consistent method is provided to handle error messages in PCL through the message facility.
It is based around a set of utilities and a unified index to a separate database (messages.database)
which contains the actual text strings corresponding to each unique error code (1->2**31). Also
provided with the message facility is a set of forms to display the errors (Use msg_to_form to
invoke this for internally generated errors). Since the user cannot add to the text strings in
messages.database, user_message is provided to allow access to the same forms.

appcode ( status )

Description:
Return the multiple of 1000000 ignoring the remainder of status. Used to determine the
application which originated the error status code.
Input:
INTEGER status Application error status code.
Output:
INTEGER <Return Value> Return status of operation.
Example:
Please see appcode (p. 843) in the MSC.Acumen, Volume 2: Code Examples.

app_db_err_msg ( domesg, db_routine, caller, status, id )

Description:
Handle a database error.
Input:
LOGICAL domesg Error message flag: If TRUE, this routine will issue a message if
an error is encountered.
STRING db_routine[] Name of the database routine that detected the error.
STRING caller[] Name of the routine that called the database routine.
INTEGER status Database status code.
INTEGER id Id of item causing the error.
Output:
none
Example:
Please see app_db_err_msg (p. 839) in the MSC.Acumen, Volume 2: Code Examples.

msg_format_string ( msgcode, ints, reals, chars, string )

Description:
PCL interface to Message Utility for getting message into string(s).
Input:
INTEGER msgcode Message code to look up.
INTEGER ints() Integer array for formatting.
Main Index
CHAPTER 5 91
User Interface

REAL reals() Real array for formatting.


STRING chars[] Character array start for formatting.
Output:
STRING string[] String containing the resulting message.
INTEGER <Return Value> This function returns the number of characters in the string
returned in the output value string.
Example:
Please see msg_format_string (p. 851) in the MSC.Acumen, Volume 2: Code Examples.

msg_get_application ( msgcode )

Description:
Get Application code embedded in a message code.
Input:
INTEGER msgcode Message code to look up.
Output:
INTEGER <Return Value> Application code extracted from msgcode.
Example:
Please see msg_get_application (p. 853) in the MSC.Acumen, Volume 2: Code Examples.

msg_string_more ( string )

Description:
Get next piece of message string.
Input:
none
Output:
STRING string[] Return string containing up to the total number of characters
in the message string. The string can be declared to any length.
INTEGER <Return Value> Number of characters left.
Example:
Please see msg_string_more (p. 854) in the MSC.Acumen, Volume 2: Code Examples.

msg_to_file ( msgcode, msgtype, appcode, ints, reals, chars, maxout, unit )

Description:
Output a message to a PCL fio unit.
Input:
INTEGER msgcode Message code to look up.
INTEGER msgtype Message type.
INTEGER appcode Application code for calling application.
INTEGER ints() Integer array for formatting.
Main Index
92
Function Descriptions

REAL reals() Real array for formatting.


STRING chars[] Character array (Fortran style) for formatting.
INTEGER maxout Maximum output size in string.
INTEGER unit Channel from TEXT_OPEN call.
Output:
INTEGER <Return Value> Number of characters left.
Example:
See example for msg_string_more (p. 91). See also msg_to_file (p. 855) in the MSC.Acumen,
Volume 2: Code Examples.

msg_to_string ( msgcode, msgtype, appcode, ints, reals, chars, string )

Description:
Interface to Message utility to retrieve Message from message database.
Input:
INTEGER msgcode Message code to look up.
INTEGER msgtype Message type.
INTEGER appcode Application code for calling application.
INTEGER ints() Integer array for formatting.
REAL reals() Real array for formatting.
STRING chars[] Character array for formatting.
Output:
STRING string[] String to return first part of message in to.
INTEGER <Return Value> Number of characters left in string.
Example:
Please see msg_to_string (p. 856) in the MSC.Acumen, Volume 2: Code Examples.

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.

Main Index
CHAPTER 5 93
User Interface

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. 905) in the MSC.Acumen, Volume 2: Code Examples.

notemessage.text ( label, message )

Description:
Simple note message form with Ok button.
Input:
STRING label[] Form label.
STRING message[] Message text (Include \n for new line).
Output:
none
Example:
Please see notemessage.text (p. 858) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
94
Function Descriptions

5.2 List Processor


The list processor parses lists of entities typed in by the user into databoxes in the standard
Picklist syntax or generated from picking graphical entities with the cursor.

Include files
The following include files define symbols used with certain list processor functions:
lpkeywords.i
lpenums.i
geometry_types.i
geometry_coos.i

app_count_list ( type, list, domesg, status )

Description:
Count the number of items of a specified type that are contained in a list.
Input:
INTEGER type Item type ( for example lp_sublist_curve from “lpenums.i” )
STRING list[] Input list from user interface.
LOGICAL domes Error message flag: If TRUE, this routine will issue a message if
LIST produces an error condition during list processing.
Output:
INTEGER status List processor status code: 0 = ok.
INTEGER <Return Value> Number of TYPE items in LIST ( -1 if error encountered ).
Example:
Please see app_count_list (p. 836), and app_count_list (p. 837) in the MSC.Acumen, Volume 2:
Code Examples.

app_ids_to_vstring ( id_array, numval, type, appstr )

Description:
This function will create a string from an array of integer id and label values.
Input:
INTEGER id_array(numval) This value specifies the integer id and label values used to
create a string.
INTEGER numval This value specifies the number of offsets defined for the
input value id_array.
INTEGER type This value specifies the list processor entity type that the
integer id and label values represent. This value can range
from 1 to 16.
Output:
INTEGER appstr [VIRTUAL] This value returns the string created from the integer id
and label values.
INTEGER <Return Value> This function will always return a value of zero.
Main Index
CHAPTER 5 95
User Interface

Example:
Please see app_ids_to_vstring (p. 840) in the MSC.Acumen, Volume 2: Code Examples.

app_int_array_to_vstring ( prefix, numvals, inlist, virtsym )

Description:
This function will create a list processor string of entity identifiers from a list of label values.

Input:
STRING prefix[] Prefix string, max be null or empty.
INTEGER numvals The number of values in the input list.
INTEGER inlist() The int array input list of ids to convert.
Output:
STRING virtsym[VIRTUAL] Virtual string to receive character list.
INTEGER <Return Value> Success = 0, else message code.
Example:
Please see app_int_array_to_vstring (p. 842) in the MSC.Acumen, Volume 2: Code Examples.

asm_u_coord_global_to_local ( <points>, <trans_vector>, <rot_matrix >, <i_type>,


<num_points>)

Description:
Transform points from global coordinates to local. Pass the transpose of the rotation matrix
stored in the database. The real array points() which is used as an input to the function returns
the new coordinates of the points.
Input:
REAL ARRAY points() The point coordinates in global frame.
REAL ARRAY trans_vector() This value specifies the translation vector for the local
coordinate frame.
REAL ARRAY rot_matrix() This value specifies the rotation matrix for the local
coordinate frame and is the transpose of the rotation
matrix stored in the database.
INTEGER i_type The reference coordinate frame type:
1=rectangular
2=cylindrical
3=spherical
Any other integer defaults to rectangular.
INTEGER num_points The number of points.
Output:
REAL points() The point coordinates in local frame
Error Conditions:
None.
Example:
Please see asm_u_coord_global_to_local (p. 843) in the MSC.Acumen, Volume 2: Code Examples.
Main Index
96
Function Descriptions

asm_u_lp_get_entity_label (label_handle, list, last_supplied_label, domesg, label,


status)

Description:
Get an ASM entity label from the user supplied entity label list.
Input:
INTEGER label_handle Pointer to the list evaluator allocated structure for the
entity labels.
STRING list[] User input list.
LOGICAL last_supplied_label True if the list of user supplied entity labels has been
exhausted prematurely and the remaining entity labels
will be assigned by the database.
LOGICAL domesg Error message flag: If TRUE, this routine will allow the
app_db_err_msg routine to issue a message if an error is
encountered.
Output:
INTEGER label Label of asm entity to create.
INTEGER status The list processor status flag.
=0: successful.
Example:
Please see asm_u_lp_get_entity_label (p. 844) in the MSC.Acumen, Volume 2: Code Examples.

asm_u_lp_get_point (point_list, do_message, point, status )

Description:
Uses list processor to get a point.
Input:
STRING point_list[] The point list.
LOGICAL do_message =TRUE if subroutine to handle errors.
Output:
REAL point() The x, y, z coordinates of the point.
INTEGER status =0: successful.
!=0: error, returns error code.
Example:
Please see asm_u_lp_get_point (p. 845) in the MSC.Acumen, Volume 2: Code Examples.

asm_u_lp_get_vector ( vector, do_message, vector_coord, status )

Description:
Uses list processor to get the x, y, z parts of a vector.
Input:
STRING vector[] The vector list.
LOGICAL do_message =TRUE if subroutine to handle errors.

Main Index
CHAPTER 5 97
User Interface

Output:
REAL vector_coord() The x, y, z coordinates of the vector.
INTEGER status =0: successful.
!=0: error, returns error code.
Example:
Please see asm_u_lp_get_vector (p. 846) in the MSC.Acumen, Volume 2: Code Examples.

lp_eval_cleanup ( handle )

Description:
Free allocated memory for list processor operations. This function must be called after all calls
to parse a particular picklist.
Input:
INTEGER handle Handle returned from lp_eval.
Output:
INTEGER <Return Value> Always returns 0.
Example:
Please see lp_eval_cleanup (p. 848) in the MSC.Acumen, Volume 2: Code Examples.

lp_geometry_text ( geo_keyword, geo_id_count, geo_id_list, text_len_max, text )

Description:
Create a geometry Picklist from a prefix and array of integers.
Input:
INTEGER geo_keyword Geometry type (From lpkeywords.i)
INTEGER geo_id_count Number of ids in array.
INTEGER geo_id_list ( ) List of ids.
INTEGER text_len_max Number of characters in text.
Output:
STRING text[VIRTUAL] Picklist syntax string.
INTEGER <Return Value> See error conditions.
Error Conditions:
14000199 LpGeometryText: there isn’t enough room to build the output string.
Example:
Please see lp_geometry_text (p. 849) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
98
Function Descriptions

lp_keyword_text ( keyword, family, text )

Description:
The purpose of this function is to return the keywords found in MSC.Patran that are used by
MSC.Patran to describe objects, actions, etc.
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 4
#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

Main Index
CHAPTER 5 99
User Interface

Output:
STRING text[31] String alias for keyword.
INTEGER <Return Value> Message facility code. See Message System Functions
(p. 114) in the PCL and Customization. 0 indicates no error.
Example:
Please see lp_keyword_text (p. 850) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
100
Function Descriptions

5.3 General

uid_get_screen_info ( xpix, ypix, width, height, dpi )

Description:
Return the setting of screen size in pixels and pixels per inch.
Input:
none
Output:
INTEGER xpix The number of pixels in the x screen direction.
INTEGER ypix The number of pixels in the y screen direction.
INTEGER width The pixel width of the screen.
INTEGER height The pixel height of the screen.
INTEGER dpi The number of dots (pixels) per inch in the x direction.
Error Conditions:
14000199 LpGeometryText: there isn’t enough room to build the output string.
Example:
Please see uid_get_screen_info (p. 883) in the MSC.Acumen, Volume 2: Code Examples.

uid_get_border_sizes ( type, pos_is_frame, leftoffset, topoffset, rightoffset,


bottomoffset )

Description:
Return the value of positionIsFrame and the size of the borders in all four directions for a
specific type of window.
Input:
INTEGER type Window type:
0=dialog
1=graphics
2=modal
Output:
LOGICAL pos_is_frame Setting of PositionIsFrame.
INTEGER leftoffset Size of left border.
INTEGER topoffset Size of top border.
INTEGER rightoffset Size of right border.
INTEGER bottomoffset Size of bottom border.
Example:
See example for uid_get_screen_info (p. 100). See also uid_get_border_sizes (p. 882) in the
MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 5 101
User Interface

uid_get_font_heights ( font_ht, textfont_ht, spreadfont_ht )

Description:
Return font heights.
Input:
none
Output:
INTEGER font_ht Font height in pixels.
INTEGER textfont_ht Text font height in pixels.
INTEGER spreadfont_ht Spreadsheet font height in pixels.
Example:
Please see uid_get_font_heights (p. 883) in the MSC.Acumen, Volume 2: Code Examples.

uid_set_sys_pix ( pix_per_inch, new_disp_factor )

Description:
Calculate system dimensions.
Input:
REAL pix_per_inch Set monitor pixels per inch.
REAL new_disp_factor Set the display factor.
Output:
none
Example:
See example for uid_get_font_heights (p. 101). See also uid_set_sys_pix (p. 884) in the
MSC.Acumen, Volume 2: Code Examples.

uil_app_analysis.get_real_name ( user_name, real_name )

Description:
Get the current preference from the database.
Input:
STRING user_name[] The current analysis code or type name. See
db_get_default_anal_code.
Output:
STRING real_name[] The modified analysis code or analysis type name.
Example:
Please see uil_app_analysis.get_real_name (p. 885) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
102
Function Descriptions

uil_pcntcomplete.close ()

Description:
This function closes the percent complete form in the MSC.Patran window. The function has no
return value.
Input:
None.
Output:
None.
Error Conditions:
None.
Example:
Please see uil_pcntcomplete.close (p. 886) in the MSC.Acumen, Volume 2: Code Examples.

uil_pcntcomplete.initlz (<label>)

Description:
This function starts the percent complete status form in the MSC.Patran window. The function
has no return value.
Input:
STRING label [] The label for the percent complete form.
Output:
None.
Error Conditions:
None.
Example:
Please see uil_pcntcomplete.initlz (p. 886) in the MSC.Acumen, Volume 2: Code Examples.

uil_primary.get_menubar_id ( )

Description:
Returns the widget id of the main menu bar
Input:
none
Output:
WIDGET <Return Value> Value of the main menu bar id.
Example:
Please see uil_primary.get_menubar_id (p. 887) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 5 103
User Interface

ui_sys_command ( cmd )

Description:
Can be used to create new files outside the MSC.Patran environment, or perform any other unix
task in the invoking window.
Input:
STRING cmd[] Unix command.
Output:
LOGICAL <Return Value> True- Unsuccessful. False- Successful.
Example:
Please see ui_sys_command (p. 873) in the MSC.Acumen, Volume 2: Code Examples.

ui_sys_return ( )

Description:
Return out of the event loop. This will cause the application to return to the operating system
command line.
Input:
none
Output:
none
Example:
Please see ui_sys_return (p. 874) in the MSC.Acumen, Volume 2: Code Examples.

ui_text_select ( textwid, left, right, vstr )

Description:
Return selected text and it’s left and right positions in the string in which it resides.
Input:
WIDGET textwid The widget ID.
Output:
INTEGER left Left position.
INTEGER right Right position.
STRING vstr[ ] This value returns the text selected in the textbox. See the
notes below.
Notes:
This string must be allocated with enough characters to contain the entire string. If enough
characters are not allocated, the text box string returned by this function will be truncated.
A string with enough characters to contain the selected text can be allocated with a call to the
ui_wid_get_vstring () function as shown in the example.
Example:
Please see ui_text_select (p. 874) and ui_text_select (p. 875) in the MSC.Acumen, Volume 2:
Code Examples.
Main Index
104
Function Descriptions

ui_wid_exit ( )

Description:
Call the exit function for all displayed windows.
Input:
none
Output:
none
Example:
Please see ui_wid_exit (p. 877) in the MSC.Acumen, Volume 2: Code Examples.

ui_wid_hide_forms ( parm )

Description:
Call the hide all function for all displayed windows to hide all the displayed windows. Used
for applications such as Insight which need to hide all the forms with one call.
Input:
STRING parm[] “ALL”, “NONGRAPHICS”, “NONMODAL”, “MODAL”,
“GRAPHICS”, “DB” .
Output:
none
Example:
Please see ui_wid_hide_forms (p. 877) in the MSC.Acumen, Volume 2: Code Examples.

ui_exec_command ( cmd )

Description:
Invokes a MSC.Patran command.
Input:
STRING cmd[] Command to be invoked.
Output:
none
Example:
Please see ui_exec_command (p. 861) in the MSC.Acumen, Volume 2: Code Examples.

ui_form_delete ( class )

Description:
Delete the form defined in the given group.
Input:
STRING class[] Form’s group name.

Main Index
CHAPTER 5 105
User Interface

Output:
none
Example:
Please see ui_form_delete (p. 861) in the MSC.Acumen, Volume 2: Code Examples.

ui_form_exists ( class )

Description:
This function will determine if a form has been initialized.
Input:
STRING class[] This value specifies the name of the class that implements the
form.
Output:
LOGICAL <Return Value> TRUE if the given groupname has been initialized.
Notes:
This function will work only with forms that are created throug a call to ui_form_create () made
in an init function that is a member of the class of functions represented by the input value
class. In all other cases this function will return FALSE.
Example:
Please see ui_form_exists (p. 862) in the MSC.Acumen, Volume 2: Code Examples.

ui_form_is_displayed ( class )

Description:
This function will determine if a form is currently being displayed.
Input:
STRING class[] Name of the class to be searched for in the list of currently
displayed forms.
Output:
LOGICAL <Return Value> TRUE: The class form is currently displayed.
FALSE: The class form is NOT displayed.
Notes:
This function will work only with forms that are created through a call to ui_form_create ()
made in an init function that is a member of the class of functions represented by the input
value class. In all other cases this function will return FALSE.
The value specified for the input argument class is case sensitive. If this function does not
behave as described, try changing the case of the name passed with that argument.
Example:
Please see ui_form_is_displayed (p. 864) and ui_form_is_displayed (p. 865) in the
MSC.Acumen, Volume 2: Code Examples.

Main Index
106
Function Descriptions

ui_graph_create ( parent, name, x, y, width, height )

Description:
Create a graphics widget.
Input:
WIDGET parent Pointer to the parent widget.
STRING name[] Name of the graphics widget.
REAL x X location.
REAL y Y location.
REAL width Widget width.
REAL height Widget height.
Output:
WIDGET <Return Value> Pointer to the new widget.
Example:
Please see ui_graph_create (p. 869) and ui_graph_create (p. 870) in the MSC.Acumen,
Volume 2: Code Examples.

ui_is_initialized ( )

Description:
Check to see if the user interface has been initialized.
Input:
none
Output:
LOGICAL <Return Value> User interface has been initialized.
User interface has not been initialized.
Example:
Please see ui_is_initialized (p. 871) in the MSC.Acumen, Volume 2: Code Examples.

ui_get_client ( client_info )

Description:
Get the X client.
Input:
none
Output:
STRING client_info [80] X client.
Example:
Please see ui_get_client (p. 867) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 5 107
User Interface

ui_get_server ( server_info )

Description:
Get the X server.
Input:
none
Output:
STRING server_info[] X server.
Example:
See example for ui_get_client (p. 106). See also ui_get_server (p. 869) in the MSC.Acumen,
Volume 2: Code Examples.

Main Index
108
Function Descriptions

5.4 Widgets

ui_clear_focus ( wid )

Description:
Clear the input focus for a widget.
Input:
WIDGET wid Pointer to the widget.
Output:
none
Example:
Please see ui_clear_focus (p. 860) in the MSC.Acumen, Volume 2: Code Examples.

ui_wid_restore_widget ( wid )

Description:
Restore the values for this widget and all child widgets.
Input:
WIDGET wid Widget ID.
Output:
LOGICAL <Return Value> TRUE if no error.
Example:
Please see ui_wid_restore_widget (p. 878) in the MSC.Acumen, Volume 2: Code Examples.

ui_wid_save_widget ( wid )

Description:
Save the values for this widget and all child widgets.
Input:
WIDGET wid Pointer to the widget.
Output:
LOGICAL <Return Value> TRUE if no error.
Example:
Please see ui_wid_save_widget (p. 880) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 5 109
User Interface

uil_utils_listbox.select ( lbox_id, label )

Description:
Highlight a “name” in the listbox.
Input:
WIDGET lbox_id ID of listbox to modify. This is the ID returned by a call to the
PCL functions ui_listbox_items_create or
uil_utils_listbox.create_list
STRING label[] Name in listbox to highlight. This list of names is the list of
labels used by the PCL functions ui_listbox_items_create and
uil_utils_listbox.create_list.
Output:
LOGICAL <Return Value> TRUE if no error.
Example:
Please see uil_utils_listbox.select (p. 899) in the MSC.Acumen, Volume 2: Code Examples.

uil_utils_listbox.select_none ( lbox_id )

Description:
Clear all highlighted names in the listbox.
Input:
WIDGET lbox_id ID of listbox to modify.
Output:
LOGICAL <Return Value> TRUE if no error.
Example:
Please see uil_utils_listbox.select_none (p. 903) in the MSC.Acumen, Volume 2: Code Examples.

uil_utils_listbox.select_list (list_box_id, label_list, list_count)

Description:
This function will select or highlight a list of names in a listbox.
Input:
WIDGET list_box_id This value specifies the identifier of the listbox.
STRING label_list[31](list_count)
This value specifies the list of labels in the listbox that will be
highlighted. These labels are defined when the listbox is
created and are typically a maximum of 31 characters long.
INTEGER list_count This value specifies the number of labels specified by the
input value label_list.
Output:
LOGICAL <Return Value> This function will return a value of TRUE if an error has not
occurred and a value of FALSE if an error has occurred.
Error Conditions:
None.
Main Index
110
Function Descriptions

Remarks:
None.
Example:
Please see uil_utils_listbox.select_list (p. 902) in the MSC.Acumen, Volume 2: Code Examples.

uil_utils_listbox.create_list ( lbox_id, labellist, listcnt )

Description:
Create a list of items in the listbox from the given names.
Input:
WIDGET lbox_id ID of listbox to modify.
STRING labellist[]() List of names in listbox to create.
INTEGER listcnt Number of items in labellist.
Output:
none
Example:
Please see uil_utils_listbox.create_list (p. 889) in the MSC.Acumen, Volume 2: Code Examples.

uil_utils_listbox.append_list ( lbox_id, labellist, listcnt )

Description:
Append a list of items in the listbox from the given names.
Input:
WIDGET lbox_id ID of listbox to modify.
STRING labellist[]() List of name items to append.
INTEGER listcnt Number of items in labellist.
Output:
none
Example:
See example for uil_utils_listbox.create_list (p. 110). See also uil_utils_listbox.append_list
(p. 888) in the MSC.Acumen, Volume 2: Code Examples.

uil_utils_listbox.get_selected ( lbox_id, items, num )

Description:
Get the selected items in the listbox.
Input:
WIDGET lbox_id ID of listbox to modify.
Output:
STRING items [xx] Items selected. xx needs to be equal to or larger than the
(VIRTUAL) length of the largest item in the listbox.
INTEGER num Number of items selected.
Main Index
CHAPTER 5 111
User Interface

Example:
Please see uil_utils_listbox.get_selected (p. 896) in the MSC.Acumen, Volume 2: Code Examples.

uil_utils_listbox.get_unselected ( lbox_id, items, num )

Description:
Get the unselected items in the listbox.
Input:
WIDGET lbox_id ID of listbox to modify.
Output:
STRING items [xx] Items selected. xx needs to be equal to or larger than the
(VIRTUAL) length of the largest item in the listbox.
INTEGER num Number of items selected.
Example:
Please see uil_utils_listbox.get_unselected (p. 898) in the MSC.Acumen, Volume 2: Code
Examples.

uil_utils_listbox.get_all ( lbox_id, items, num )

Description:
Get all items in the listbox
Input:
WIDGET lbox_id ID of listbox widget
Output:
STRING items [VIRTUAL] Listbox items.
(VIRTUAL)
INTEGER num Number of items in listbox.
Example:
See example for uil_utils_listbox.create_list (p. 110). See also uil_utils_listbox.get_all
(p. 895) in the MSC.Acumen, Volume 2: Code Examples.

uil_utils_listbox.delete_item ( lbox_id, name )

Description:
Delete a given item from the set of listbox items.
Input:
WIDGET lbox_id Id of listbox to modify.
STRING name[] Name in listbox to delete.
Output:
LOGICAL <Return Value> TRUE if no error, FALSE if name does not exist.
Example:
See example for uil_utils_listbox.create_list (p. 110). See also uil_utils_listbox.delete_item
(p. 890) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
112
Function Descriptions

uil_utils_listbox.delete_item_list ( lbox_id, nitems, itemlist )

Description:
Delete a list of given items from the listbox.
Input:
WIDGET lbox_id Id of listbox to modify.
INTEGER nitems The number of items in the list.
STRING itemlist[]() Names in listbox to delete.
Output:
none
Example:
See example for uil_utils_listbox.create_list (p. 110). See also
uil_utils_listbox.delete_item_list (p. 892) in the MSC.Acumen, Volume 2: Code Examples.

uil_utils_listbox.delete_selected ( lbox_id )

Description:
Deletes from the listbox the selected items.
Input:
WIDGET lbox_id Id of listbox to modify.
Output:
none
Example:
Please see uil_utils_listbox.delete_selected (p. 893) in the MSC.Acumen, Volume 2: Code
Examples.

uil_utils_listbox.select_all ( lbox_id )

Description:
Highlight all names in the listbox.
Input:
WIDGET lbox_id Id of listbox to modify.
Output:
none
Example:
See example for uil_utils_listbox.select (p. 109). See also uil_utils_listbox.select_all (p. 901)
in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 5 113
User Interface

5.5 Help

ui_get_help ( wid, help )

Description:
Get the help keyword registered for the given widget.
Input:
WIDGET wid Pointer to the widget.
Output:
STRING help[] Keyword used for searching.
Example:
Please see ui_get_help (p. 867) in the MSC.Acumen, Volume 2: Code Examples.

ui_register_help ( wid, help )

Description:
Register help for the given widget.
Input:
WIDGET wid Pointer to the widget.
STRING help[] Keyword used for searching.
Output:
none
Example:
Please see ui_register_help (p. 871) in the MSC.Acumen, Volume 2: Code Examples.

ui_add_help ( keyword, path, marker )

Description:
Adds a record to the help table, providing the connection from the keyword in the widget to the
help file and to the entry in that file.
Input:
STRING keyword[] Unique keyword to locate the marker in the frame document.
STRING path[] Path to the frame document.
STRING marker[] Frame hypertext marker.
Output:
INTEGER <Return Value> 0 for no error.
1 for duplicate.
Comments:
When the help keyword is triggered due to a request for help, the frame document as specified
in the path is opened and positioned to the specified hypertext marker. The path given is
typically a partial path to a help file, such as “userapp/appinfo.doc”. MSC.Patran will search
for this file path in each directory in the PCL path starting with the current directory. If not
Main Index
114
Function Descriptions

found MSC.Patran will then see if a unix environment variable “P3_HELP_DIRECTORY” is set
and if so will search under this directory for the file. If still not found, MSC.Patran will look for
a directory called “helpfiles” in the PCL path and look for the file path under that directory.
Used in conjunction with ui_register_help.
Example:
Please see ui_add_help (p. 858) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Group
6
■ General
■ FEM
■ Geometry
■ Graphics Application

Main Index
116
Function Descriptions

6.1 General
General functions for managing groups in the model database.

db_get_group_name (grp_id, name)

Description:
Retrieves the group name associated with the specified group id.
Input:
INTEGER grp_id Id to be retrieved from the database.
Output:
STRING name[31] Name of the group.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_get_group_name (p. 928) in the MSC.Acumen, Volume 2: Code Examples.

db_count_entities_in_group (name, type, count)

Description:
Counts all entities in the specified group name.
Input:
STRING name[] Pointer to a string containing the name of the group.
INTEGER type The type of entity to be counted.
Output:
INTEGER count Location to receive the resulting entity count.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_count_entities_in_group (p. 918) in the MSC.Acumen, Volume 2: Code Examples.

db_count_groups_for_entity (id, type, count)

Description:
Counts all groups in which a specified entity resides
Input:
INTEGER id The id of the entity for which the group count is desired.
INTEGER type The type of entity to be counted.
Output:
INTEGER count Location to receive the resulting entity count.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_count_groups_for_entity (p. 919) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 6 117
Group

db_get_groups_for_entity (id, type, count, group_list)

Description:
Gets all group ids associated with the specified entity type and id.
Input:
INTEGER id The id of the entity of the type specified.
INTEGER type The type of entity to be counted.
INTEGER count The number of groups for which storage has been
allocated by the calling routine.
Output:
INTEGER group_list() Array containing the ids of the groups associated with the
input id.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
See example for db_count_groups_for_entity (p. 116). See also db_get_groups_for_entity
(p. 929) in the MSC.Acumen, Volume 2: Code Examples.

uil_entity_group_members_get (group, entity_type, members)

Description:
Get the group’s members of a given entity type.
Input:
STRING group[] Name of the group from which to get the list of members.
INTEGER entity_type Type of entity members to get.
DbTypPoint 1
DbTypCurve 2
DbTypSurface 3
DbTypSolid 4
DbTypNode 123
DbTypElem 124
DbTypMpc 161
Output:
STRING members [VIRTUAL]
INTEGER <Return Value> List of group members of the given entity type.
= 0, Function was successful.
Example:
See also uil_entity_group_members_get (p. 993) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
118
Function Descriptions

6.2 FEM
Utilities for manipulating nodes, elements and MPCs in a group or groups.

db_get_groups_using_mpc (nmpc, mpcid, maxgrp, ngroup, gid)

Description:
Returns a list of all groups which refer to the specified MPC.
Input:
INTEGER nmpc The number of MPCs ids for which the information is
being requested.
INTEGER mpcid() The ids of the MPCs for which the information is being
requested.
INTEGER maxgrp The maximum number of groups which may be returned
per MPC.
Output:
INTEGER ngroup() The number of groups using each MPC.
INTEGER gid() The ids of the groups for each MPC.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000142 The MPC was not found in the database.
13000154 The list of Groups for one or more of the MPCs is longer than MAXGRP.
External Dependencies and Side Effects:
Accesses records in the mpc_in_group table in the database.
Example:
Please see db_get_groups_using_mpc (p. 930) in the MSC.Acumen, Volume 2: Code Examples.

db_count_groups_using_mpc (nmpc, mpcid, ngroup, flag)

Description:
Returns the number of groups which refer to the specified MPCs.
Input:
INTEGER nmpc The number of MPCs ids for which the information is
being requested.
INTEGER mpcid() The ids of the MPCs for which the information is being
requested.
Output:
INTEGER ngroup() The number of groups using each MPC.
INTEGER flag An error flag indicating that one or more of the MPCs was
not found.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Main Index
CHAPTER 6 119
Group

Error Conditions:
13000142 The MPC was not found in the database.
External Dependencies and Side Effects:
Accesses records in the mpc_in_group table in the database.
Example:
See example for db_get_groups_using_mpc (p. 118). See also
db_count_groups_using_mpc (p. 920) in the MSC.Acumen, Volume 2: Code Examples.

db_count_orphan_mpcs (count)

Description:
Returns the number of entities not in a group.
Input:
none
Output:
INTEGER count The number of entities not in a group.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000086 No Records Found
External Dependencies and Side Effects:
This routine accesses records in the mpc & mpc_in_group tables in the database.
Example:
Please see db_count_orphan_mpcs (p. 924) in the MSC.Acumen, Volume 2: Code Examples.

db_get_orphan_mpcs (count, entity_id)

Description:
Gets the entities not in a group.
Input:
INTEGER count The number of entities not in a group.
Output:
INTEGER entity_id() Array of orphan entity ids.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000086 No Records Found
External Dependencies and Side Effects:
This routine accesses records in the mpc & mpc_in_group tables in the database.
Example:
See example for db_count_orphan_mpcs (p. 119). See also db_get_orphan_mpcs (p. 932) in
the MSC.Acumen, Volume 2: Code Examples.

Main Index
120
Function Descriptions

count_orphan_elements (count)

Description:
This function will count all of the elements that do not belong to any group. It will build a list of
these elements in the process and this list will be saved for a subsequent call to
get_orphan_elements (p. 120).
Input:
none
Output:
INTEGER count The number of elements not associated with any group.
INTEGER <Return Value> 0 = Successful Completion.
Example:
See example for get_orphan_elements (p. 120). See also count_orphan_elements (p. 914) in
the MSC.Acumen, Volume 2: Code Examples.

count_orphan_nodes (count)

Description:
This function will count all of the nodes that do not belong to any group. It will build a list of
these nodes in the process and this list will be saved for a subsequent call to
get_orphan_nodes (p. 121).
Input:
none
Output:
INTEGER count The number of nodes not associated with any group.
INTEGER <Return Value> 0 = Successful Completion.
Example:
See example for get_orphan_nodes (p. 121). Please see count_orphan_nodes (p. 915) in the
MSC.Acumen, Volume 2: Code Examples.

get_orphan_elements ( count, idlist )

Description:
Returns the list of all of the elements that do not belong to any group. The initial list is created
through a call to the function count_orphan_elements (p. 120).
Input:
INTEGER count This is the number of orphan elements.
Output:
INTEGER idlist(count) The number of nodes not associated with any group.
INTEGER <Return Value> 0 if Successful.
Example:
Please see get_orphan_elements (p. 988) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 6 121
Group

get_orphan_nodes ( count, idlist )

Description:
Returns the list of all of the elements that do not belong to any group. The initial
list is created through a call to the function count_orphan_nodes (p. 120).
Input:
INTEGER count This is the number of orphan nodes.
Output:
INTEGER idlist(count) This is an array of orphan node ids that has ‘count’
number of members in the array.
INTEGER <Return Value> 0 if Successful.
Example:
Please see get_orphan_nodes (p. 989) in the MSC.Acumen, Volume 2: Code Examples.

db_add_mpc_to_group ( mpc_id, gid, visible )

Description:
Add an mpc to a group.
Input:
INTEGER mpc_id The mpc id.
INTEGER gid The group id.
LOGICAL visible True (1) if the mpcs are to be considered visible.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000142 The MPC was not found in the database.
13000008 Group not found.
13000004 Duplicate entry exists in table.
External Dependencies and Side Effects:
Creates a record in the mpc_in_group table in the database.
Example:
Please see db_add_mpc_to_group (p. 917) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
122
Function Descriptions

6.3 Geometry
Utilities for managing points, curves, surfaces, and solids in conjunction with groups.

db_count_orphan_curves ( count )

Description:
Returns the number of curves not in a group.
Input:
none
Output:
INTEGER count The number of curves not in a group.
INTEGER <Return Value> Returns the success or failure of the routine
Example:
Please see db_count_orphan_curves (p. 921) and db_count_orphan_curves (p. 922) in the
MSC.Acumen, Volume 2: Code Examples.

db_get_orphan_curves ( count, label_id )

Description:
This function will return the label ids for curves that are not assigned to a group.
Input:
INTEGER count This value specifies the number of offsets defined for the
output value label_id.
Output:
INTEGER entity_id() This value returns the label id values of the orphan
curves.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Example:
See example for db_count_orphan_curves (p. 122) for more information. See also
db_get_orphan_curves (p. 931) in the MSC.Acumen, Volume 2: Code Examples.

db_count_orphan_points ( count )

Description:
Returns the number of points not in a group.
Input:
none
Output:
INTEGER count The number of points not in a group.
INTEGER <Return Value> Returns the success or failure of the routine
Main Index
CHAPTER 6 123
Group

Example:
Please see db_count_orphan_points (p. 925) in the MSC.Acumen, Volume 2: Code Examples.

db_get_orphan_points ( count, entity_id )

Description:
Returns the point entities not in a group.
Input:
INTEGER count Max number of entities returned.
Output:
INTEGER entity_id() Array of orphan eitity ids.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
See example for db_count_orphan_points (p. 122). See also db_get_orphan_points (p. 933)
in the MSC.Acumen, Volume 2: Code Examples.

db_count_orphan_solids ( )

Description:
Returns the number of solids not in a group.
Input:
none
Output:
INTEGER count The number of solids not in a group.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_count_orphan_solids (p. 926) in the MSC.Acumen, Volume 2: Code Examples.

db_get_orphan_solids ( count, entity_id )

Description:
Returns the solid entities not in a group.
Input:
INTEGER count Max number of entities returned.
Output:
INTEGER entity_id() Array of orphan entity ids.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
See example for db_count_orphan_solids (p. 123). See also db_get_orphan_solids (p. 934)
in the MSC.Acumen, Volume 2: Code Examples.

Main Index
124
Function Descriptions

db_count_orphan_surfaces ( count )

Description:
Returns the number of surfaces not in a group.
Input:
none
Output:
INTEGER count The number of surfaces not in a group.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_count_orphan_surfaces (p. 927) in the MSC.Acumen, Volume 2: Code Examples.

db_get_orphan_surfaces ( count, entity_id )

Description:
Returns the surface entities not in a group.
Input:
INTEGER count Max number of entities returned.
Output:
INTEGER entity_id() Array of orphan entity ids.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
See example for db_count_orphan_surfaces (p. 124). Please see db_get_orphan_surfaces
(p. 935) in the MSC.Acumen, Volume 2: Code Examples.

asm_db_count_asm_in_group ( groupId, count, status )

Description:
Counts all of the The MacNeal-Schwendler Corporation entities (grid, line, patch, hpat,
coordinate frames, nodes, and elements) in a group.
Input:
INTEGER groupId The id of the group.
Output:
INTEGER count(7) The count for each of the entities:
(1) - grid
(2) - line
(3) - patch
(4) - hpat
(5) - coordinate frames
(6) - nodes
(7) - elements
INTEGER status Success or an error code.
Example:
Please see asm_db_count_asm_in_group (p. 908) in the MSC.Acumen, Volume 2: Code
Examples.
Main Index
CHAPTER 6 125
Group

asm_db_get_grids_in_group ( groupId, gridLabels, xyzCoordinates, status )

Description:
Gets the labels and xyz coordinates of all the grids in a group.
Input:
INTEGER groupId The id of the group.
Output:
INTEGER gridLabels() The grid labels.
REAL xyzCoordinates() The xyz coordinates.
INTEGER status Success or an error code.
Error Conditions:
38000617 ERROR Retrieving geometric entity definition of type PDA %A% from the
database.
Example:
Please see asm_db_get_grids_in_group (p. 909) in the MSC.Acumen, Volume 2: Code Examples.

asm_db_get_hpats_in_group (groupid, hpatlabels, hpatvertexids, geometriccoeff,


status)

Description:
This function will get the labels, hpat vertex ids, and the xyz coordinates of all the hpats in a
group.
Input:
INTEGER groupid This value specifies the id of the group.
Output:
INTEGER hpatlabels() This value returns the hpat label values. The number of
offsets for this array should equal the number of solids
defined for the group.
INTEGER hpatvertexIds() This value returns the hpat vertex ids. The number of
offsets for this array should equal the number of solids
defined for the group times 8.
REAL geometriccoeff() This value returns the xyz coordinates. The number of
offsets for this array should equal the number of solids
defined for the group times 192.
INTEGER status This value returns a value of 0 when the function executes
successfully and a non zero value to indicate a change in
status or an error.
Remarks:
The number of solids defined in a group can be found by calling the function
db_count_entities_in_group (p. 116). with the entity type value set to 4.
Example:
Please see asm_db_get_hpats_in_group (p. 910) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
126
Function Descriptions

asm_db_get_lines_in_group ( groupid, linelabels, geometriccoefficients, status )

Description:
Gets the labels and xyz coordinates of all the lines in the model.
Input:
INTEGER groupId The id of the group.
Output:
INTEGER linelabels() The line labels.
REAL geometriccoefficients() The xyz coordinates.
INTEGER status Success or an error code.
Error Conditions:
38000617 ERROR Retrieving geometric entity definition of type PDA %A% from the
database.
Example:
Please see asm_db_get_lines_in_group (p. 911) in the MSC.Acumen, Volume 2: Code Examples.

asm_db_get_patches_in_group ( groupid, patchlabels, geometriccoeff, status )

Description:
This function will get the labels and the xyz coordinates of all of the patches in a group.
Input:
INTEGER groupid This value specifies the id of the group.
Output:
INTEGER patchlabels() This value returns the patch label values. The number of
offsets for this array should equal the number of surfaces
defined for the group.

REAL geometriccoeff() This value returns the xyz coordinates. The number of
offsets for this array should equal the number of surfaces
defined for the group times 48.
INTEGER status This value returns a value of 0 when the function executes
successfully and a non zero value to indicate a change in
status or an error.
Remarks:
The number of surfaces defined in a group can be found by calling the function
db_count_entities_in_group (p. 116) with the entity type value set to 3.
Example:
Please see asm_db_get_patches_in_group (p. 913) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 6 127
Group

sgm_db_count_iges_in_group ( groupid, count )

Description:
Counts all the IGES entity types IN A GROUP.
Input:
INTEGER groupId The id of the group.
Output:
INTEGER count (15) The count for each of the entities:
(1) - IGES_Nurb_Curve.
(2) - IGES_Cubic_Spline.
(3) - IGES_Arc.
(4) - IGES_Composite_Curve.
(5) - IGES_Line.
(6) - IGES_Conic.
(7) - IGES_PieceWise_Linear.
(8) - IGES_Offset_Curve.
(9) - IGES_Nurb_Surface.
(10) - IGES_Trimmed_Surface.
(11) - IGES_BiCubic_Patch_Network.
(12) - IGES_Surface_Of_Revolution.
(13) - IGES_Ruled_Surface.
(14) - IGES_Tabulated_Cylinder.
(15) - IGES_Offset_Surface.
INTEGER <Return Value> See error conditions.
Error Conditions:
1000025 Error attempting to allocate virtual memory.
Example:
Please see sgm_db_count_iges_in_group (p. 990) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_db_get_iges_in_group ( groupid, typecode, entityids, id_count )

Description:
This function will get all the IGES entity types in a group.
Input:
INTEGER groupid This value specifies the id of the group.
INTEGER typecode This value specifies the type code of the group. See the
remarks below.
Output:
INTEGER entityids() This value returns the entity id values. This array must be
allocated with enough offsets to list all of the entity id
values assigned to the group. Use a call to the PCL
function sgm_db_count_iges_in_group() to get a count of
the number of offsets required.
INTEGER id_count This value returns the number of id values of the
specified type returned by the value entityids.

Main Index
128
Function Descriptions

INTEGER <Return Value> This function returns a value of 0 when executed


successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
38000617 ERROR Retrieving geometric entity definition of type PDA %A% from the
database.
Remarks:
The input value typecode can be assigned the following values:
Value: Description:
102 IGES_Nurb_Curve
103 IGES_Cubic_Spline
104 IGES_Arc
105 IGES_Composite_Curve
106 IGES_Line
107 IGES_Conic
108 IGES_PieceWise_Linear
113 IGES_Offset_Curve
1001 IGES_Nurb_Surface
1002 IGES_Trimmed_Surface
1003 IGES_BiCubic_Patch_Network
1004 IGES_Surface_Of_Revolution
1005 IGES_Ruled_Surface
1006 IGES_Tabulated_Cylinder
1012 IGES_Offset_Surface
Example:
Please see sgm_db_get_iges_in_group (p. 991) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 6 129
Group

6.4 Graphics Application


Functions to manage graphical attributes of groups.

ga_groups_load_vector_set ( ngroups, group_ids, vector_id )

Description:
Changes the current load vector table associated with multiple groups.
Input:
INTEGER ngroups Number of groups.
INTEGER group_ids ( ) Groups to assign vector table to.
INTEGER vector_id Load vector id.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000143 The specified vector result table was not found.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_groups_load_vector_set (p. 984) and ga_groups_load_vector_set (p. 986) in
the MSC.Acumen, Volume 2: Code Examples.

ga_group_color_get ( name, color )

Description:
Gets the current color associated with a group.
Input:
STRING name[] Group name.
Output:
INTEGER color Color of group (0-15).
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_color_get (p. 936) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
130
Function Descriptions

ga_group_color_set ( name, color )

Description:
Modifies the current color associated with a group.
Input:
STRING name[] Group name.
INTEGER color Color id (0-15).
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_color_set (p. 937) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_current_get ( name )

Description:
Get the current group.
Input:
none
Output:
STRING name[] Group name.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000121 There is not a current group defined.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_current_get (p. 938) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_deform_get ( name, flag )

Description:
Gets the deform flag associated with a group.
Input:
STRING name[] Group name.
Output:
INTEGER flag Deform flag.
INTEGER <Return Value> See error conditions.

Main Index
CHAPTER 6 131
Group

Error Conditions:
11000050 The group name is invalid.
11000098 A fatal error has occurred in the database. Database is corrupted.
11000105 The specified group was not found in the database.
Example:
Please see ga_group_deform_get (p. 939) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_deform_set ( name, flag )

Description:
Sets whether a deform plot should be displayed.
Input:
STRING name[] Group name.
INTEGER flag If Flag=1 display deform plot, If Flag=0 don’t display.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000098 A fatal error has occurred in the database. Database is corrupted.
11000105 The specified group was not found in the database.
Example:
Please see ga_group_deform_set (p. 940) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_display_get ( name, dname )

Description:
Gets the name of the current display property list associated with a group.
Input:
STRING name[] Group name.
Output:
STRING dname[] Name of the display property list.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000118 There is no display property posted to the group.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_display_get (p. 941) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
132
Function Descriptions

ga_group_elem_scalar_get ( name, scalar_id )

Description:
Gets the scalar table associated with a group.
Input:
STRING name[] Group name.
Output:
INTEGER scalar_id Scalar id.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_elem_scalar_get (p. 943) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_elem_scalar_set ( name, scalar_id )

Description:
Changes the current element scalar table associated with a group.
Input:
STRING name[] Group name.
INTEGER scalar_id Element scalar id.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000137 The specified element scalar table was not found.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_elem_scalar_set (p. 944) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_entities_get ( name, type, range, number, entities )

Description:
Gets a sorted list of the entities contained in a group.
Input:
STRING name[] Group name.
INTEGER type Entity type.
INTEGER range (3) Id range of members to return (1,2) and (3) max size of
conversion string.
INTEGER number Number of entities in group.
Main Index
CHAPTER 6 133
Group

Output:
STRING entities[] Entity labels.
INTEGER <Return Value> See error conditions.
Comments:
Called from PCL ( uil_group_modify.pcl, uil_group_modify_members.pcl,
uil_group_show_members).
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
11000127 The group does not have any entities in it.
Example:
Please see ga_group_entities_get (p. 946) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_exist_get ( name, flag )

Description:
Determines if a group with the specified name exists.
Input:
STRING name[] Group name.
Output:
INTEGER flag Existence flag.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_exist_get (p. 947) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_groups_get ( group_list )

Description:
This function will get a list of the currently defined groups.
Input:
none
Output:
STRING group_list [ ] () List of groups.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.

Main Index
134
Function Descriptions

Example:
#
# Purpose : This file gives an example of a call to the
# function ga_group_groups_get()
#
# This function gets the list of all the groups.
# This file opens a database spool.db which has
# two groups “default_group”and “fem_model”group.
# This file gets the list of all the groups in
# the database “spool.db”.
#
# Before running this file the database should be
# created by running the session file “spool.ses”
# To run this session file, first start
# a session of MSC.Patran,then run this session
# file by “File”,”Session”,”Play” pulldown
# menus on the menu bar.
#
# The ga_group_groups_get has the following arguments:
# ga_group_groups_get
# ( group_list )
# -------------------------------------------------------------------
# Variable Declaration
#
STRING s_group_list[32](VIRTUAL)
INTEGER i_return_value
INTEGER i_group_count
# -------------------------------------------------------------------
# opening the existing database spool.db
uil_file_open.go(“spool.db”)

i_return_value =
ga_group_ngroups_get
( i_group_count )

dump i_return_value
dump i_group_count

i_return_value =
sys_allocate_array ( s_group_list, 1, i_group_count )

dump i_return_value

i_return_value = @
ga_group_groups_get @
( s_group_list )

dump i_return_value

# The groups in the opened database are


dump s_group_list

# -------------------------------------------------------------------

Main Index
CHAPTER 6 135
Group

ga_group_label_get ( name, flag )

Description:
Gets the current label flag associated with a group.
Input:
STRING name[] Group name.
Output:
INTEGER flag Label flag.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_label_get (p. 949) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_label_set ( name, flag )

Description:
Sets whether labels should be displayed.
Input:
STRING name[] Group name.
INTEGER flag If Flag=1 display deform plot, If Flag=0 don’t display.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_label_set (p. 950) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_load_vector_get ( name, vector_id )

Description:
Gets the load vector table associated with a group.
Input:
STRING name[] Group name.
Output:
INTEGER vector_id Vector id.
INTEGER <Return Value> See error conditions.

Main Index
136
Function Descriptions

Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_load_vector_get (p. 951) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_load_vector_set ( name, vector_id )

Description:
Changes the current load vector table associated with a group.
Input:
STRING name[] Group name.
INTEGER vector_id Load vector id.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000143 The specified vector result table was not found.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_load_vector_set (p. 953), ga_group_load_vector_set (p. 954), and
ga_group_load_vector_set (p. 956) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_nentities_get ( name, type, number )

Description:
Gets the number of entities of a particular type contained in the specified group.
Input:
STRING name[] Group name.
INTEGER type Entity type.
Output:
INTEGER number Number of entities.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_nentities_get (p. 958) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 6 137
Group

ga_group_ngroups_get ( group_count )

Description:
This function will get the number of currently defined groups.
Input:
None.
Output:
INTEGER group_count This value will return the number of groups that are
currently defined.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_groups_get (p. 948) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_node_deform_set ( name, deform_id )

Description:
Changes the current deform table associated with a group.
Input:
STRING name[] Group name.
INTEGER deform_id Node deform id.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000139 The specified nodal deformation table was not found.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_node_deform_set (p. 959) and ga_group_node_deform_set (p. 960) in
the MSC.Acumen, Volume 2: Code Examples.

Main Index
138
Function Descriptions

ga_group_precision_get ( name, flag )

Description:
Gets the current precision flag associated with a group.
Input:
STRING name[] Group name.
Output:
INTEGER flag Flag=1 if high precision, Flag=0 if fast.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_precision_get (p. 962) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_result_vector_get ( name, vector_id )

Description:
Gets the result vector table associated with a group.
Input:
STRING name[] Group name.
Output:
INTEGER vector_id Vector id.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_result_vector_get (p. 963) and ga_group_result_vector_get (p. 965) in
the MSC.Acumen, Volume 2: Code Examples.

ga_group_result_vector_set ( name, vector_id )

Description:
Changes the current result vector table associated with a group.
Input:
STRING name[] Group name.
INTEGER vector_id Result vector id.
Output:
INTEGER <Return Value> See error conditions.

Main Index
CHAPTER 6 139
Group

Error Conditions:
11000050 The group name is invalid.
11000143 The specified vector result table was not found.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Pleae see ga_group_result_vector_set (p. 967) and ga_group_result_vector_set (p. 969) in
the MSC.Acumen, Volume 2: Code Examples.

ga_group_selectable_get ( name, flag )

Description:
Gets the current select status of a group.
Input:
STRING name[] Group name.
Output:
INTEGER flag 1 or 0 if selectable or not.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_selectable_get (p. 971) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_selectable_set ( name, flag )

Description:
Modifies the current setting of the group selectable flag.
Input:
STRING name[] Group name.
INTEGER flag 1 or 0 if selectable or not.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_selectable_set (p. 973) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
140
Function Descriptions

ga_group_style_get ( name, style )

Description:
Gets the render style associated with a group.
Input:
STRING name[] Group name.
Output:
STRING style[] Render style.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_style_get (p. 974) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_style_set ( name, style )

Description:
Modifies the render style associated with a group.
Input:
STRING name[] Group name.
STRING style[] Render Style.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000013 The render style is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_style_set (p. 975) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_vector_load_get ( name, style )

Description:
Gets the load vector flag associated with a group.
Input:
STRING name[] Group name.
Output:
INTEGER flag Vector flag.
INTEGER <Return Value> See error conditions.

Main Index
CHAPTER 6 141
Group

Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_vector_load_get (p. 977) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_vector_load_set ( name, flag )

Description:
Flags if a load vector plot should be displayed with group.
Input:
STRING name[] Group name.
INTEGER flag If Flag=1 display vector plot, If Flag=0 don’t display.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_vector_load_set (p. 978) in the MSC.Acumen, Volume 2: Code Examples.

ga_group_vector_result_get ( name, flag )

Description:
Gets the load vector flag associated with a group.
Input:
STRING name[] Group name.
Output:
INTEGER flag Vector flag.
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_vector_result_get (p. 979) and ga_group_vector_result_get (p. 980) in
the MSC.Acumen, Volume 2: Code Examples.

Main Index
142
Function Descriptions

ga_group_vector_result_set ( name, flag )

Description:
Flags if a result vector plot should be displayed with group.
Input:
STRING name[] Group name.
INTEGER flag If Flag=1 display vector plot, If Flag=0 don’t display.
Output:
INTEGER <Return Value> See error conditions.
Error Conditions:
11000050 The group name is invalid.
11000105 The specified group was not found in the database.
11000098 A fatal error has occurred in the database. Database is corrupted.
Example:
Please see ga_group_vector_result_set (p. 982) and ga_group_vector_result_set (p. 983) in
the MSC.Acumen, Volume 2: Code Examples.

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Geometry
7
■ General
■ Point
■ Curve
■ Surface

■ Solid
■ Coordinate Frame
■ Point/Curve Relation
■ Curve/Surface Relation
■ Surface/Solid Relation
■ Transform

Main Index
144
Function Descriptions

7.1 General
A set of general utilities are provided to manage geometry in the model database.

db_get_geom_type ( id_label, entity_type, geom_type )

Description:
Returns the geometry type for the given label and entity_type.
Input:
INTEGER id_label The label id of the piece of geometry.
INTEGER entity_type The type of entity.
point = 1
curve = 2
surface = 3
solid = 4
Output:
STRING geom_type[] The type of geometry.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000161 The geometric type is not defined.
13000134 The specified entity type was not found.
Example:
Please see db_get_geom_type (p. 1030) in the MSC.Acumen, Volume 2: Code Examples.

sgm_db_get_blob_size ( entitytype, entityid, blobsize, status )

Description:
This function will return the size of a block of data defining a specific piece of geometry.
Input:
INTEGER entitytype This value specifies the type of the geometry for which
the data block will be retrieved. See the remarks listed
below for more information.
INTEGER entityid This value specifies the identifier for the geometry for
which the data block will be retrieved.
Output:
INTEGER blobsize The value returns the size of the of the array needed to
hold the block of data defining the geometry.
INTEGER status This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
38000003 No blob provided.

Main Index
CHAPTER 7 145
Geometry

Remarks:
The input value entitytype can be set to the following values:
Value Description

2 This value describes a piece of geometry that represents a curve.


3 This value describes a piece of geometry that represents a surface.
4 This value describes a piece of geometry that represents a solid.
174 This value describes a piece of geometry that represents a plane.
175 This value describes a piece of geometry that represents a vector.
Example:
Please see sgm_db_get_blob_size (p. 1072) in the MSC.Acumen, Volume 2: Code Examples.

sgm_db_get_company_of_origin ( dbtype, entityid, compoforg, geometrytype, status )

Description:
Gets a geometric coo and type from the database given an id.
Input:
INTEGER dbtype The dbtype from dbtypes.h.
INTEGER entityid The Entity ID.
Output:
INTEGER compoforg The company of origin.
From include file geometry_coos.i

Company of Origin compoforg


PDA_ENGINEERING 52054
MCDONNELL_DOUGLAS 101254
DASSAULT_SYSTEMS 40686
PARAMETRIC_TECHNOLOGY 22058
IGES 62738
MATRA 32465
PDES 112762
COMPUTER_VISION 22085

INTEGER geometrytype The geometry type.


INTEGER status 0 or an error code.
Example:
Please see sgm_db_get_company_of_origin (p. 1073) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
146
Function Descriptions

sgm_db_modify_entity_label ( entitytype, entityid, newlabel )

Description:
Modifies the label of an existing geometric entity.
Input:
INTEGER entitytype Type of entity from DbTypes.
INTEGER entityid Id of the entity to change.
INTEGER newlabel Label to be assigned to the entity.
Output:
INTEGER <Return Value> 0: no error.
Error Conditions:
10000052 %A% %I% is not an ASM Entity and was not written to the MSC.Patran Neutral
File.
Example:
Please see sgm_db_modify_entity_label (p. 1089) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_incongruent_geom_exist ( )

Description:
Initialize the geometry list.
Input:
none
Output:
INTEGER <Return Value> 0: no error.
1: fatal error.
Example:
Please see sgm_incongruent_geom_exist (p. 1112) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_incongruent_geom_display ( )

Description:
Creates a graphical display list for curves and surfaces, but displays all unique points and
solids. Need to call sgm_verify_surface_boundary first.
Input:
none
Output:
INTEGER <Return Value> 0 if function was successful.
Comments:
This routine cannot display points or solids because of graphics restrictions.
Example:
Please see sgm_incongruent_geom_display (p. 1111) in the MSC.Acumen, Volume 2: Code
Main Index
Examples.
CHAPTER 7 147
Geometry

sgm_incongruent_geom_seg_exit ( )

Description:
Delete the segment list to clear graphics.
Input:
none
Output:
INTEGER <Return Value> Success returned, else fatal error.
Comments:
Used with sgm_incongruent_geom_exist() and sgm_incongruent_geom_display()
Example:
See example for sgm_incongruent_geom_exist (p. 146). See also
sgm_incongruent_geom_seg_exit (p. 1112) in the MSC.Acumen, Volume 2: Code Examples.

sgm_u_calc_mscale_mat ( coord_org, coord_rmat, translation, scale, axis_base,


axis_tip, rotation_angle, tmat )

Description:
Calculates a transformation matrix for a mscale transformation.
Input:
REAL coord_org (3) Reference coordinate frame origin.
REAL coord_rmat (9) Reference coordinate frame rotation matrix.
REAL translation (3) Translation vector.
REAL scale (3) Scale factors.
REAL axis_base (3) Axis base (for rotation).
REAL axis_tip (3) Axis tip (for rotation).
REAL rotation_angle Rotation angle.
Output:
REAL tmat (16) This value returns the calculated transformation matrix.
INTEGER <Return Value> SUCCESS or error code.
Example:
Please see sgm_u_calc_mscale_mat (p. 1127) in the MSC.Acumen, Volume 2: Code Examples.

asm_u_coord_global_to_local ( p, t, r, itype, npts )

Description:
Transform points from global coordinates to local. Pass the transpose of the rotation matrix
stored in the database.
Input:
REAL p(3,npts) The point coordinates in global frame.

Main Index
148
Function Descriptions

REAL t(3) This value specifies the translation vector for the local
coordinate frame.
REAL r(3,3) This value specifies the rotation matrix for the local
coordinate frame and is the transpose of the rotation
matrix stored in the database.
INTEGER ityper The reference coordinate frame type:
1=rectangular
2=cylindrical
3=spherical
INTEGER npts The number of points.
Output:
REAL p(3,npts) The point coordinates in local frame.
Example:
Please see asm_u_coord_global_to_local (p. 1009) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 7 149
Geometry

7.2 Point

asm_db_create_grid (location, grid_label, yes_to_all, no_to_all, yes_to_all_dup,


no_to_all_dup, status)

Description:
This function creates a grid in the database and the graphical user-interface.
Input:
REAL ARRAY location(3) The xyz location of the point.
INTEGER grid_label Label of next grid to create.
=0 Database will use the next highest label for the next
grid to create. If grid found within tolerance, returns
currently existing grid label, otherwise returns new label.
>0 User-definable.
LOGICAL yes_to_all = TRUE if grid already exists in database with same label
and user wants to overwrite old grid with new grid.
LOGICAL no_to_all = TRUE if grid already exists in database with same label
and user does not want to overwrite old grid with new
grid.
LOGICAL yes_to_all_dup = TRUE if grid already exists in database within tolerance
and same label and user wants to create duplicate grids.
LOGICAL no_to_all_dup = TRUE if grid already exists in database within tolerance
and same label and user does not want to create duplicate
grids.
Output:
INTEGER status The value of 0 is returned when executed successfully
and a non zero value to indicate a change in status or an
error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see asm_db_create_grid (p. 1002) in the MSC.Acumen, Volume 2: Code Examples

db_count_point ( count )

Description:
Counts all points in the database.
Input:
none
Output:
INTEGER count The integer number of points in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.

Main Index
150
Function Descriptions

Example:
Please see db_count_point (p. 1017) in the MSC.Acumen, Volume 2: Code Examples.

db_get_max_point_label ( label )

Description:
Gets the largest point label from the database.
Input:
none
Output:
INTEGER label Highest point label used.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_max_point_label (p. 1032) in the MSC.Acumen, Volume 2: Code Examples.

db_get_min_point_label ( label )

Description:
Gets the smallest point label from the database.
Input:
none
Output:
INTEGER label Lowest point label used.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_min_point_label (p. 1036) in the MSC.Acumen, Volume 2: Code Examples.

db_get_point_association_count ( point_id, assoc_count )

Description:
Returns the number of higher order entities associated with this point.
Input:
INTEGER point_id The point id.
Output:
INTEGER assoc_count The number of higher order entities associated with this
point.
INTEGER <Return Value> Returns the success or failure of the routine.

Main Index
CHAPTER 7 151
Geometry

Example (session file):


Please see db_get_point_association_count (p. 1041) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_point_id ( label, id )

Description:
Gets a point id from the database given a point label.
Input:
INTEGER label The unique external point ID identifying the point to be
retrieved from the database.
Output:
INTEGER id The unique internal point id identifying the point
retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_point_id (p. 1043) in the MSC.Acumen, Volume 2: Code Examples.

db_get_point_label ( id, label )

Description:
Gets a point label from the database given a point id.
Input:
INTEGER id The unique internal point id identifying the point to be
retrieved from the database.
Output:
INTEGER label The unique external point id identifying the point to be
retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_point_label (p. 1043) in the MSC.Acumen, Volume 2: Code Examples.

db_get_point_coo_and_type ( id, coo, type )

Description:
Gets a geometric coo and type from the database given an id.
Input:
INTEGER id The association of the information to be retrieved from
the database.

Main Index
152
Function Descriptions

Output:
INTEGER coo The geometric company of origin stored in the database.
INTEGER type The geometric type of data stored in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_point_coo_and_type (p. 1042) in the MSC.Acumen, Volume 2: Code
Examples.

asm_db_get_next_grid_label ( domessage, integerlabel, stringlabel )

Description:
Get the next highest grid label from the database.
Input:
LOGICAL domessage Tells the routine to issue an error message if an error
occurs.
Output:
INTEGER integerlabel The next highest grid label.
STRING stringlabel[] The next highest grid label.
INTEGER <Return Value> Success or an error code.
Example:
Please see asm_db_get_next_grid_label (p. 1005) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_db_get_point ( pointid, xyz, status )

Description:
Get the geometric definition of a point from the database.
Input:
INTEGER pointid Id of the point.
Output:
REAL xyz (3) Global coordinates of a point.
INTEGER status Success or an error code.
Example:
Please see sgm_db_get_point (p. 1086) in the MSC.Acumen, Volume 2: Code Examples.

sgm_edit_point_equivalence (point_ids, created_ids)

Description:
This function checks the equivalence of two points and deletes one of the duplicate points.
Input:

Main Index
CHAPTER 7 153
Geometry

STRING point_ids[ ] The points whose equivalence is to be checked.

Output:
STRING created_ids[ ] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see sgm_edit_point_equivalence (p. 1093) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_get_close_points (point_location, tolerance, num_only, vertices_only,


sort_option, num_point, point_ids, distances )
Description:
This function gets the points around a point within a specified distance.
Input:
REAL point_location(3) The xyz location of the point in space.
ARRAY
REAL tolerance The distance within which to search for points.
INTEGER num_only 1 to get the num of points only, 0 to get the point ids and
the distances.
INTEGER vertices_only 0 to get all points, 1 to get vertices only.
INTEGER sort_option 1 to sort the point ids and distances.

Output:
INTEGER num_point The number of points within the tolerance around the
location.
INTEGER point_ids(num_points) Point ids of the points.
ARRAY
REAL distances(num_points) Distances of the points from the location specified.
ARRAY
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_get_close_points (p. 1106) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
154
Function Descriptions

sgm_node_on_point ( geotol, num_pts, pt_id_list, num_nodes, node_id_list )

Description:
Get the nodes close to the given points within the geometric tolerance.
Input:
REAL geotol The geometric tolerance.
INTEGER num_pts The number of the given points.
INTEGER pt_id_list (num_pts) The ID list of the given points.
Output:
INTEGER num_nodes ( ) The number of the nodes found.
INTEGER node_id_list The ID list of the nodes found.
(num_nodes)
INTEGER <Return Value> Success or an error code.
Error Conditions:
1000025 Error attempting to allocate virtual memory.
1000305 Coordinates for point %I% not found.
1000303 No points were found to exist in the database as defined in the point list. The
point list input was %A%.
48000004 No Node found !
Example:
Please see sgm_node_on_point (p. 1118) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 7 155
Geometry

7.3 Curve

asm_db_get_curve_geo ( curve_id, geo_coefs, status )

Description:
Get the geometric format of a curve.
Input:
INTEGER curve_id Curve id (internal db id).
Output:
REAL geo_coefs(12) Geometric coefficients of the curve.
INTEGER status 0 , no error.
-1 , data base not responding.
Example:
Please see asm_db_get_curve_geo (p. 1003) in the MSC.Acumen, Volume 2: Code Examples.

asm_db_get_next_line_label ( domessage, integerlabel, stringlabel )

Description:
Get the next highest line label from the database.
Input:
LOGICAL domessage Tells the routine to issue an error message if an error
occurs.
Output:
INTEGER integerlabel The next highest curve label.
STRING stringlabel 0 , no error.
-1 , data base not responding.
INTEGER <Return Value> Success or an error code.
Example:
Please see asm_db_get_next_line_label (p. 1008) in the MSC.Acumen, Volume 2: Code
Examples.

asm_const_curve_2d_arc2point_v2 (output_ids, num_curves, arc_method,


radius,create_center, center_rev_direction,
arc_angle,plane_list, center_point_list,
start_point_list,end_point_list, project_points,
created_ids)

Description:
This function creates an arc from ‘two points and center point’ or from ‘start, end point and
radius’.
Input:

Main Index
156
Function Descriptions

STRING output_ids[] This value specifies the curve ID list. If this value is set to an
empty string or to “#”, the function will automatically
allocate and assign a sequential list of curve IDs.
INTEGER num_curves Number of curves to be created.
INTEGER arc_method This value specifies the arc method: 1 = define arc by center,
start and end points, and 2 = define arc by start point, end
point and radius.
REAL radius This value specifies the arc radius if the input value
arc_method is set to 2.
LOGICAL create_center This value is set to TRUE if the arc center point is to be
created along with the arc and if the input value
arc_method is equal to 2.
LOGICAL center_rev_direction This value is set to TRUE if the arc center is to be
flipped/rotated in the counter-clockwise direction before
the arc is created and if the input value arc_method is equal
to 2.
INTEGER arc_angle This value specifies the arc angle to use: 1 = minimum arc
angle, and 2 = maximum arc angle.
STRING plane_list[] This value specifies the list of planes in which to construct
the arcs.
STRING center_point_list[] This value specifies the list of points defining the center
points of the circular arcs.
STRING start_point_list[] This value specifies the list of points defining the starting
points of the circular arcs.
STRING end_point_list[] This value specifies the list of points defining the ending
points of the circular arcs.
LOGICAL project_points This value specifies, when set to TRUE, that the center
points be projected onto the plane. When this value is set to
FALSE and the input value arc_method is not set to 2, the
construction plane will be translated to the center point
location and will still be parallel to the original plane. If this
value is set to FALSE and the input value arc_method is set
to 2, the construction plane is translated to the starting
point location and will still be parallel to the original plane.
Output:
STRING created_ids[VIRTUA This value returns the created ID list.
L]
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
38000845 Unable to acquire %I% words of virtual memory.
38000424 The center point and start point define a zero radius.
38000413 Zero length plane normal vector
38000440 Invalid 2D Arc2Point method. Must be 1 or 2. Try again.
1000578 The number of Curves per Arc must be greater than or
equal to one. The invalid value input was %I%
38000442 The Radius value of %G% is too small for the input start
and end points. Radius magnitude must be at least %G%.
Modify application input and try again.
Main Index
CHAPTER 7 157
Geometry

38000418 The Arc radius must be greater than zero. Invalid value
input was %G%
Example:
Please see asm_const_curve_2d_arc2point_v2 (p. 997) in the MSC.Acumen, Volume 2: Code
Examples.

asm_const_curve_2d_arc3point_v1 (output_ids, num_curves, create_center,


plane_list, start_list, mid_list, end_list,
project_flag, created_ids)

Description:
This function creates an arc-shaped or parametric cubic curve in two dimensional space,
defined by a start point, midpoint, and an end point.
Input:
STRING output_ids[] This value specifies the curve ID list. If this value is set to
an empty string or to “#”, the function will automatically
allocate and assign a sequential list of curve IDs.
INTEGER num_curves This value specifies the number of curves per arc to
create.
LOGICAL create_center This value is set to TRUE if a point is to be created at the
center of the arc.
STRING plane_list[] This value specifies the construction plane of the arc.
STRING start_list[] This value specifies the start point of the arc.
STRING mid_list[] This value specifies the midpoint of the arc.
STRING end_list[] This value specifies the end point of the arc.
LOGICAL project_flag TRUE if the center point is to be projected onto the plane.
Output:
STRING created_ids[VIRTUAL] This value returns the created ID list.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
38000845 Unable to acquire %I% words of virtual memory.
38000423 The three points specified are nearly collinear.
38000413 Zero length plane normal vector
1000578 The number of Curves per Arc must be greater than or
equal to one. The invalid value input was %I%
Example:
Please see asm_const_curve_2d_arc3point_v1 (p. 998) in the MSC.Acumen, Volume 2: Code
Examples.

asm_const_curve_2d_circle_v1 (output_ids, num_curves, radius_method, radius,


plane_list, radius_point_list, center_point_list,
created_ids)

Description:
Main Index
158
Function Descriptions

This function creates a circular-shaped or parametric cubic curve in two-dimensional space,


defined by a center point and a radius.
Input:
STRING output_ids[] This value specifies the curve ID list. If this value is set to
an empty string or to “#”, the function will automatically
allocate and assign a sequential list of curve IDs.
INTEGER num_curves This value specifies the number of curves per circle to
create.
INTEGER radius_method This value specifies the method used to define a radius: 1
= scalar radius value, and 2 = point location.
REAL radius This value specifies the radius of the circle if the input
value radius_method is set to 1.
STRING plane_list[] This value specifies the list of planes in which to
construct the arcs.
STRING radius_point_list[] This value specifies the list of points defining the radius
of the circle if the input value radius_method is set to 2.
STRING center_point_list[] This value specifies the list of points defining the center
point of the circle.
LOGICAL project_flag TRUE if the center point is to be projected onto the plane.
Output:
STRING created_ids[VIRTUAL] This value returns the created ID list.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
38000845 Unable to acquire %I% words of virtual memory.
38000413 Zero length plane normal vector
38000425 The Circle radius must be greater than zero. Invalid value
input was %G%
38000426 The center point and start point define a zero radius.
1000579 The number of Curves per Circle must be greater than or
equal to two. The invalid value input was %I%.
Example:
Please see asm_const_curve_2d_circle_v1 (p. 999) in the MSC.Acumen, Volume 2: Code
Examples.

asm_const_curve_project_v1 (output_ids, curve_list, entity_list, entity_type,


delete_original, method, vector, coord_frame,
num_curves, projection_tolerance, created_ids)

Description:
This function creates a parametric cubic curve from the projection of curves onto surfaces.
Input:
STRING output_ids[] This value specifies the curve ID list. If this value is set to
an empty string or to “#”, the function will automatically
allocate and assign a sequential list of curve IDs.
STRING curve_list[] This value specifies the curve list to project.
STRING entity_list[] This value specifies the entity list to project onto.
Main Index
CHAPTER 7 159
Geometry

INTEGER entity_type The entity type to be projected.


LOGICAL delete_original This value is set to TRUE if the original curves to project
are to be deleted after the projection. If this value is set to
FALSE, the original entities will not be deleted.
INTEGER method This value specifies the projection method: 1 = the curve
to be projected lies in a plane and it is desired to project
the curve normal to this plane, 2 = the direction of
projection is normal to the surface at the point of closest
approach, 3 = the direction of projection is given by a
vector, and 4 = the direction of projection is the view
vector.
STRING vector[] This value specifies the projection vector.
STRING coord_frame[] This value specifies the coordinate frame ID for the
projection vector.
INTEGER num_curves This value specifies the number of curves per projection
to create. If this value is set to 0, then the number of
curves created will be based on the projection tolerance.
REAL projection_tolerance This value specifies a tolerance parameter determining
the density of intersection points generated.
Output:
STRING created_ids[VIRTUAL] This value returns the created ID list.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see asm_const_curve_project_v1 (p. 1000) in the MSC.Acumen, Volume 2: Code
Examples.

curve_arc_to_parm (curve_id, num_values, arc_lengths, parametric_coord, status )

Description:
This function determines the corresponding coordinates for various input values of percent
arclength along a curve.
Input:
INTEGER curve_id The id of the curve for which data is required.
INTEGER num_values The number of values for which the
parametric coordinates are required.
REAL ARRAY arc_lengths(num_values) Array of arc lengths at which the parameters
are desired.
Output:
REAL ARRAY parametric_coord(num_values)Array of parametric coordinates for the curve.
INTEGER status This function returns a value of 0 when
executed successfully and a non zero value to
indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Main Index
160
Function Descriptions

Example:
Please see curve_arc_to_parm (p. 1011) in the MSC.Acumen, Volume 2: Code Examples.

curve_parm_to_arc (curve_id, num_values, parameters, arc_lengths, status )

Description:
This function determines the corresponding arc length coordinates for various input values of
parametric coordinates along a curve.
Input:
INTEGER curve_id The id of the curve for which data is required.
INTEGER num_values The number of values for which the arc lengths are
required.
REAL ARRAY parameters(num_values) Array of parametric coordinates for the curve at
which the arc lengths are desired.
Output:
REAL ARRAY arc_lengths(num_values)Array of arc lengths.
INTEGER status This function returns a value of 0 when executed
successfully and a non zero value to indicate a
change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see curve_parm_to_arc (p. 1012) in the MSC.Acumen, Volume 2: Code Examples.

db_count_curve ( count )

Description:
Counts all curves in the database.
Input:
none
Output:
INTEGER count The integer number of curves in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_count_curve (p. 1015) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 7 161
Geometry

db_get_curve_coo_and_type ( id, coo, type )

Description:
Gets a geometric coo and type from the database given an id.
Input:
INTEGER id The unique internal curve id identifying the association of
the information to be retrieved from the database.
Output:
INTEGER coo The geometric company of origin stored in the database.
INTEGER type The geometric type of data stored in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_curve_coo_and_type (p. 1026) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_curve_id ( label, id )

Description:
Gets a curve id from the database given a curve label.
Input:
INTEGER label The unique external curve id identifying the curve to be
retrieved from the database
Output:
INTEGER id The unique internal curve id identifying the curve
retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_curve_id (p. 1027) in the MSC.Acumen, Volume 2: Code Examples.

db_get_curve_label ( id, label )

Description:
Gets a curve label from the database given a curve id.
Input:
INTEGER id The unique internal curve id identifying the curve to be
retrieved from the database.

Main Index
162
Function Descriptions

Output:
INTEGER label The unique external curve id identifying the curve to be
retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_curve_label (p. 1028) in the MSC.Acumen, Volume 2: Code Examples.

db_get_max_curve_label ( label )

Description:
Gets the largest curve label from the database.
Input:
none
Output:
INTEGER label Highest curve label used.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_max_curve_label (p. 1031) in the MSC.Acumen, Volume 2: Code Examples.

db_get_min_curve_label ( label )

Description:
Gets the smallest curve label from the database.
Input:
none
Output:
INTEGER label Lowest curve label used.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_min_curve_label (p. 1035) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 7 163
Geometry

sgm_associate_nodes_curve (node_list, curve_list)

Description:
This function associates nodes with a given set of curves.
Input:
STRING node_list[ ] The list of nodes to be associated with the curves.
STRING curve_list[ ] The list of curves to which the nodes are to be associated.
Output:
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_associate_nodes_curve (p. 1052) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_const_curve_project_v1 (output_ids, curve_list, surface_list,entity_type,


delete_original, project_method, vector, coord_frame,
projection_tolerance, created_ids)
Description:
This function constructs curves on a set of surfaces by projecting an existing set of curves along
a projection vector onto a set of surfaces.
Input:
STRING output_ids[] This value specifies the curve ID list. If this value is set to
an empty string or to “#”, the function will automatically
allocate and assign a sequential list of curve IDs.
STRING curve_list[] This value specifies the list of curves to project onto the
list of surfaces.
STRING surface_list[] This value specifies the list of surfaces onto which the
curves are to be projected.
INTEGER entity_type =1 Project to surface
=2 Project to plane
LOGICAL delete_original This value is set to TRUE if the original curves are to be
deleted. If this value is set to FALSE, the original entities
will not be deleted.
INTEGER project_method This value specifies the method of defining the projection
vector: 1 = the curves to be projected lie in a plane and it
is desired to project the curves normal to this plane, 2 =
the direction of projection is normal to the surface at the
point of closest approach to the curve, 3 = the direction of
projection is to be given by a vector, and 4 = the direction
of projection is the view vector.
STRING vector[] This value specifies the projection vector.
STRING coord_frame[] This value specifies the coordinate frame for the
projection vector.

Main Index
164
Function Descriptions

REAL projection_tolerance This value specifies a tolerance parameter. The algorithm


creates all curves along the projected surface so that the
maximum distance lies between them is the distance
defined by this value.
Output:
STRING created_ids[VIRTUAL] This value returns the created ID list.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see sgm_const_curve_project_v1 (p. 1053) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_create_curve_on_surface (direction, param_value, surface_blob, curve_blob)

Description:
This function creates curve on a surface in any of the u /v directions at a given parameter and
returns the blob of the curve created.
Input:
INTEGER direction The direction to create the curve.
1 = u direction , 2 = v direction.
REAL param_value The value of the parameter for creating the curve (0 <
param_value < 1)
REAL ARRAY surface_blob() The blob of the surface on which to create the curve.
The functions to be used for getting the blob are
sgm_db_get_blob_size() followed by
sgm_db_get_surface().
Output:
REAL ARRAY curve_blob() The blob of the curve returned. The functions to be
used for getting the blob size are
sgm_db_get_blob_size() followed by
sgm_db_get_curve().
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change
in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_create_curve_on_surface (p. 1058) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 7 165
Geometry

sgm_curve_convert_s_to_u (curve_data, num_points, arc_lengths, parametric_coord,


status )
Description:
This function determines the corresponding coordinates for various input values of percent
arclength along the curve.
Input:
REAL ARRAY curve_data() The blob of curve the curve for which data is required.
The functions to be used for getting the blob are
sgm_db_get_blob_size() followed by
sgm_db_get_curve().
INTEGER num_points The number of points for which the parametric
coordinates are required.
REAL ARRAY arc_lengths Array of arc lengths at which the parameters are desired.
(num_points)
Output:
REAL ARRAY parametric_coord Array of parametric coordinates for the curve.
(num_points)
INTEGER status This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_curve_convert_s_to_u (p. 1066) in the MSC.Acumen, Volume 2: Code Examples.

sgm_curve_convert_u_to_s (curve_data, num_points, parameters, arc_lengths,


status )
Description:
This routine determines the corresponding arclength coordinates for various input values of
parametric coordinates along the curve.
Input:
REAL ARRAY curve_data() The blob of curve the curve for which data is
required. The functions to be used for getting the
blob are sgm_db_get_blob_size() followed by
sgm_db_get_surface().
INTEGER num_points The number of points for which the arc lengths are
required.
REAL ARRAY parameters(num_points) Array of parametric coordinates for the curve at
which the arc lengths are desired.
Output:
REAL ARRAY arc_lengths(num_points) Array of arc lengths at the parameters.
INTEGER status This function returns a value of 0 when executed
successfully and a non zero value to indicate a
change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Main Index
166
Function Descriptions

Example:
Please see sgm_curve_convert_u_to_s (p. 1068) in the MSC.Acumen, Volume 2: Code Examples.

sgm_curve_evaluate (blob, para_parameter, out_type, output_data, status )

Description:
This function will evaluate a data table representing the geometry of a curve, returning
information about the point of origin and the first, second, and third derivatives of the curve.
Input:
REAL blob( ) This value specifies the curve data table. This array must be
allocated with at least 6 offsets and no more than the number of
offsets set by the following formula: s(s(6)). The value stored in
the array at offset 6 must be equal to or greater than 0. See the
comments below.
REAL para_parameter This value specifies a parametric coordinate value and has a
range from 0.0 to 1.0.
INTEGER out_type This value specifies the type output expected from this function
call. See the remarks below.
Output:
REAL output_data (n,3) This value returns the output data table. See the remarks below.
INTEGER status This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an error.
Remarks:
The input value out_type can be set to the following values:
Value Description

0 Output point information only.


1 Output point and first derivative information.
2 Output point, first, and second derivative information. For an “N dimensional
cubic spline” this value would cause the point, first and second derivitive of the
first three dimensional vector to be returned.
3 Output point, first, second, and third derivatives.
The output value output_data should have its first dimension allocated to the following sizes:
para_parameter value output_data first dimensional value

0 4
1 4
2 4
3 4
A curve data table can be retrieved with a call to the sgm_db_get_curve() PCL function. The
size of the data curve table can be retrieved with a call to the PCL function
sgm_db_get_blob_size().
Example:
Please see sgm_curve_evaluate (p. 1070) in the MSC.Acumen, Volume 2: Code Examples.
Main Index
CHAPTER 7 167
Geometry

sgm_db_get_curve ( curveid, blobsize, blob, status )

Description:
Get the geometric definition of a curve from the database.
Input:
INTEGER curveid Id of the curve.
INTEGER blobsize Size of the blob in words.
Output:
REAL blob ( ) Geometric description of the curve.
INTEGER status Success or an error code.
Error Conditions:
38000001 The allocated space for the blob is too small.
Example:
See example for sgm_curve_evaluate (p. 166). See also sgm_db_get_curve (p. 1074) in
the MSC.Acumen, Volume 2: Code Examples.

sgm_db_get_curve ( curveid, blobsize, blob, status )

Description:
Get the geometric definition of a curve from the database.
Input:
INTEGER curveid Id of the curve.
INTEGER blobsize Size of the blob in words.
Output:
REAL blob ( ) Geometric description of the curve.
INTEGER status Success or an error code.
Error Conditions:
38000001 The allocated space for the blob is too small.
Example:
See example for sgm_curve_evaluate (p. 166). See also sgm_db_get_curve (p. 1074) in the
MSC.Acumen, Volume 2: Code Examples.

sgm_get_arc_center_radius (arc_id, start_point, center_point, radius)

Description
:
This function gets the start point, center point and the radius for any arc.
Input:
INTEGER arc_id The id for the arc.
Output:
REAL start_point(3) The starting point of the curve.
ARRAY
REAL center_point(3) The center point of the curve.
ARRAY
Main Index
168
Function Descriptions

REAL radius The radius of the curve.


INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_get_arc_center_radius (p. 1105) in the MSC.Acumen, Volume 2: Code Examples.

sgm_get_curve_length ( curveid, length )

Description:
Gets the length of a curve.
Input:
INTEGER curveid The ID of the curve.
Output:
REAL length The length of the curve.
INTEGER <Return Value> 0: successful, otherwise return error code.
Example:
Please see sgm_get_curve_length (p. 1108) in the MSC.Acumen, Volume 2: Code Examples.

sgm_node_on_curve ( geotol, num_crvs, crv_id_list, list_size, init_flag, num_nodes,


node_id_list, node_u_list )

Description:
Get the nodes close to the given curves within the geometric tolerance.
Input:
REAL geotol The geometric tolerance.
INTEGER num_crvs The number of the given curves.
INTEGER crv_id_lis (num_crvs) The ID list of the given curves.
INTEGER list_size The size of the node_id_list.
INTEGER init_flag Initial call ( = 0 ) or continued call ( = 1 ).
Output:
INTEGER num_nodes ( ) The number of the nodes found.
INTEGER node_id_list The ID list of the nodes found.
(num_nodes)
REAL node_u_list The list of the node parameter U.
(num_nodes)
INTEGER <Return Value> Success or an error code.
Comments:
If the node_id_list is not BIG enough to accommodate all found nodes, the return value is 9999.
Allocate another memory space, set init_flag == 1, call this routine again to get the rest nodes. (
until <return value> == 0 ).
Error Conditions:
1000025 Error attempting to allocate virtual memory.
Main Index
CHAPTER 7 169
Geometry

1000564 Data for curve %I% not found.


48000004 No Node found
1000547 No curves were found to exist in the database as defined in the curve list. The
curve list input was %A%
Example:
Please see sgm_node_on_curve (p. 1117) in the MSC.Acumen, Volume 2: Code Examples.

sgm_show_angle_between_curves (curvelist_1, curvelist_2, seg_id, marker_type,


marker_color, marker_size, angle)
Description:
This function gets the angle between any two curves and marks it on the user interface.
Input:
STRING curvelist_1[ ] The first list of curves.
STRING curvelist_2[ ] The second list of curves.
INTEGER seg_id The id of the segment for the marker.
INTEGER marker_type The type of marker for the angle.
INTEGER marker_color The color of marker for the angle.
INTEGER marker_size The size of marker for the angle.
Output:
STRING angle[ ] The value of the angle between the curve.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_show_angle_between_curves (p. 1121) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
170
Function Descriptions

7.4 Surface

asm_db_get_next_patch_label ( domessage, integerlabel, stringlabel )

Description:
Get the next highest patch label from the database.
Input:
LOGICAL domessage Tells the routine to issue an error message if an error
occurs.
Output:
INTEGER integerlabel The next highest curve label.
STRING stringlabel[] The next highest curve label.
INTEGER <Return Value> Success or an error code.
Example:
Please see asm_db_get_next_patch_label (p. 1008) in the MSC.Acumen, Volume 2: Code
Examples.

db_count_surface ( )

Description:
Counts all surfaces in the database.
Input:
none
Output:
INTEGER count The integer number of surfaces in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_count_surface (p. 1020) in the MSC.Acumen, Volume 2: Code Examples.

db_get_max_surface_label ( label )

Description:
Gets the largest surface label from the database.
Input:
none
Output:
INTEGER label
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.

Main Index
CHAPTER 7 171
Geometry

Example:
Please see db_get_max_surface_label (p. 1034) in the MSC.Acumen, Volume 2: Code Examples.

db_get_min_surface_label ( label )

Description:
Gets the smallest surface label from the database.
Input:
none
Output:
INTEGER label Highest surface label used.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_min_surface_label (p. 1037) in the MSC.Acumen, Volume 2: Code Examples.

db_get_surface_coo_and_type ( id, coo, type )

Description:
Gets a geometric coo and type from the database given an id.
Input:
INTEGER id The unique internal surface id identifying the association
of the information to be retrieved from the database.
Output:
INTEGER coo The geometric company of origin stored in the database.
INTEGER type The geometric type of data stored in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_surface_coo_and_type (p. 1048) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_surface_id ( label, id )

Description:
Gets a surface id from the database given a surface label.
Input:
INTEGER label The unique external surface id identifying the surface to
be retrieved from the database.

Main Index
172
Function Descriptions

Output:
INTEGER id The unique internal surface id identifying the surface
retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_surface_id (p. 1049) in the MSC.Acumen, Volume 2: Code Examples.

db_get_surface_label ( id, label )

Description:
Gets a surface label from the database given a surface id.
Input:
INTEGER id The unique internal surface id identifying the surface to
be retrieved from the database.
Output:
INTEGER label The unique external surface id identifying the surface to
be retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_surface_label (p. 1050) in the MSC.Acumen, Volume 2: Code Examples.

sgm_create_surface_composite_c (output_labels, surface_list, flag, gap_tolerance,


delete_cons, implicit_topology, created_labels)
Description:
This function creates composite trimmed surfaces.
Input:
STRING output_labels[ ] This value specifies the label of the surface to be
created.
STRING surface_list[ ] This value specifies the surfaces from which the
composite will be created.
INTEGER flag Inner Loop Options : 0 for All, 1 for None and 2 for
Select Edge.
REAL gap_tolerance This value specifies the gap distance for the surface
builder.
LOGICAL delete_cons This value specifies, when set to TRUE, that the
surfaces in the input value surface_list be deleted
after the composite trimmed surfaces are created.

Main Index
CHAPTER 7 173
Geometry

LOGICAL implicit_topology This value specifies, when set to TRUE, that the
edges of the created surfaces are defined by the
chain links. When this value is set to FALSE the
chain link edges will be combined if there is slope
continuity in the 2D segments.
Output:
STRING created_labels[VIRTUAL] This value returns the label of the composite surface
created.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a
change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see sgm_create_surface_composite_c (p. 1060) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_create_surface_comptrim_v1 (output_ids, surface_list, outer_curve_list,


inner_curve_list,gap_dist,delete_surface,
outer_curve_delete, inner_curve_delete,
implicit_topology, created_ids)
Description:
This function constructs a trimmed surface from a parent surface and/or outer and inner
boundary curves with an option of how to define the edges of the trimmed surfaces.
Input:
STRING output_ids[] This value specifies the surface ID list. If this value is set
to an empty string or to “#”, the function will
automatically allocate and assign a sequential list of
surface IDs.
STRING surface_list[] This value specifies the parent surface to trim.
STRING outer_curve_list[] This value specifies the outer boundary trim curves.
STRING inner_curve_list[] This value specifies the inner boundary trim curves.
REAL gap_dist The gap distance tolerance between the surfaces to be
trimmed.
LOGICAL delete_surface This value is set to TRUE if the parent surface is to be
deleted after trimmed surface is created.
LOGICAL outer_curve_delete This value is set to TRUE if the outer boundary trim
curves are to be deleted after trimmed surface is created.
LOGICAL inner_curve_delete This value is set to TRUE if the inner boundary trim
curves are to be deleted after trimmed surface is created.
LOGICAL implicit_topology This value is set to TRUE if the edges are defined from
the chain links, or to FALSE if the edges are to be derived
from the slope continuity in the 2D segments.
Output:
STRING created_ids[VIRTUAL] This value returns the created ID list.

Main Index
174
Function Descriptions

Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see sgm_create_surface_comptrim_v1 (p. 1062) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_create_surface_from_elems1 (output_ids, elem_list, preview, node_list,


in_options, in_nodes, delete_original, s_option,
corner_nodes, deleted_ids, created_ids)
Description:
This function constructs surface from any 2D element.
Input:
INTEGER output_ids[] This value specifies the surface ID list. If this value is set
to an empty string or to “#”, the function will
automatically allocate and assign a sequential list of
surface IDs.
STRING elem_list[] This value specifies the list of elements.
INTEGER preview = 1 will return 4 corner nodes.
STRING node_list[] List of nodes that represent vertices.
INTEGER in_options Defines which loops to be preserved
0 = All, 1 = None, 3 = Selected Loops
STRING in_nodes List of nodes on the loop that need to be preserved.
LOGICAL delete_original[] FALSE will delete the original elements.
INTEGER s_option[] Value for Smoother options.
0 = Fast 1 = Better Parametrization.
INTEGER corner_nodes() Returns the array of corner nodes if preview = 1
STRING deleted_ids[VIRTUAL] Deleted items.
Output:
STRING created_ids[VIRTUAL] This value returns the created ID list.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_create_surface_from_elems1 (p. 1064) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 7 175
Geometry

sgm_db_get_num_loops_face ( surfaceid, getedges, numloops, numedges,


numegploop, status )

Description:
Gets the number of loops for a surface, and the total number of edges and if desired, the
number of edges per loop.
Input:
INTEGER surfaceid The ID of the surface.
LOGICAL getedges TRUE if routine should get number of edges per loop.
FALSE if not.
Output:
INTEGER numloops The number of loops.
INTEGER numedges The total number of edges.
INTEGER numegploop ( ) The number of edges per loop (dimension is
numberLoops).
INTEGER status Success or an error code.
Comments:
The usual way to use this routine is:
1) Call it to get the number of loops numberLoops with getEdges == False (0)
2) User allocates array numberEdgesPerLoop as (INT *) MemAlloc ( arg, numberLoops *
sizeof(INT)).
3) User calls routine again with getEdges == True (1) to get the array of number of edges per
loop for all loops (numberEdgesPerLoop).
Error Conditions:
1000025 Error attempting to allocate virtual memory.
Example:
Please see sgm_db_get_num_loops_face (p. 1083) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_db_get_surface ( surfaceid, blobsize, blob, status )

Description:
Get the geometric definition of a surface from the database.
Input:
INTEGER surfaceid The ID of the surface.
INTEGER blobsize Size of the blob in words.
REAL blob ( ) Array to be filled in with Geometric description of a
surface as a blob.
Output:
REAL blob ( ) Geometric description of the surface.
INTEGER status 0: no error.
-1: database error.
-2: insufficient array length for the blob.
Error Conditions:
38000001 The allocated space for the blob is too small
Main Index
176
Function Descriptions

Example:
See example for sgm_db_get_curve (p. 167). See also sgm_db_get_surface (p. 1088) in the
MSC.Acumen, Volume 2: Code Examples.

sgm_edit_surface_edge_match (type_option, surface_list_1,surface_list_2,


delete_flag, created_ids)
Description:
This function matches the edges for adjacent surfaces which have gaps inbetween. This is
particularly relevant when surface models are imported. Such models tend to have gaps which
require closing to avoid any errors regarding continuity with adjacent surfaces. This function
works with topologically incongruent models and matches topology (edges and vertices).
Input:
INTEGER type_option[] The type of edge match to be done.
1 for surface-point
2 for surface-surface.
STRING surface_list_1[] The first list of surfaces.
STRING surface_list_2[] The second list of surfaces.
LOGICAL delete_flag This value is set to TRUE if the original surfaces are to
be deleted.
Output:
STRING created_ids[] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_edit_surface_edge_match (p. 1098) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_edit_surface_sew (surface_list, created_ids)

Description:
This function sews surfaces which have gaps inbetween. This is relevant when surface models
are imported. Such models tend to have gaps which require closing to avoid any errors
regarding continuity of the surfaces. This function will sew edges into a common boundary
between surfaces. This function was introduced to handle cases and close up gaps not possible
with just edge_match.
Input:
STRING surface_list[] The list of surfaces to be sewed.
Output:
STRING created_ids[] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.

Main Index
CHAPTER 7 177
Geometry

Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_edit_surface_sew (p. 1102) in the MSC.Acumen, Volume 2: Code Examples.

sgm_get_surface_area ( surfid, area )

Description:
Gets the area of a surface.
Input:
INTEGER surfid The ID of the surface.
Output:
REAL area The area of the surface.
INTEGER <Return Value> SUCCESS or an error code.
Example:
Please see sgm_get_surface_area (p. 1110) in the MSC.Acumen, Volume 2: Code Examples..

sgm_node_on_surface ( geo_tolerance, number_surfaces, surface_list,


number_nodes, init_flag, number_nodes_found, node_id_list,
node_uv_list )

Description:
This function will get the nodes close to the given surfaces within the geometric tolerance.
Input:
REAL geo_tolerance This value specifies the geometric tolerance.
INTEGER number_surfaces This value specifies the number of offsets in the input
value surface_list
INTEGER surface_list(number_nodes)
This value specifies a list of surface identifier values.
INTEGER number_nodes This value specifies the number of offsets defined for the
output values node_id_list and node_uv_list.
INTEGER init_flag This value specifies when set to 0 that the initial call to get
the number of nodes on the surfaces is being made. This
value specifies, when set to 1 that the call to retrieve the
list of nodes on the surfaces is being made.
Output:
INTEGER number_nodes_found (1)
This value returns the number of the nodes found on the
list of surfaces.
INTEGER node_id_list (number_nodes)
This value returns a list of the node identifiers found on
the specified surfaces.
REAL node_uv_list (number_nodes * 2)

Main Index
178
Function Descriptions

This value returns a list of parametric U and V values for


the nodes specified by the return value node_id_list. The
U and V values are listed in the order of
U1,V1,U2,V2,U3,V3,....
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
This is only a partial list of the error values that can be returned by this function.
9999 See the remarks listed below.
1000025 Error attempting to allocate virtual memory.
1000716 Data for surface %I% not found.
1000707 No surfaces were found to exist in the database as defined in the surface list. The
surface list input was %A%.
1000025 No Node found !
Remarks:
The number of nodes on a surface which is needed to correctly allocate the space for the return
values node_id_list and node_uv_list can be found by calling sgm_node_on_surface() with the
input value init_flag set to 0, the input value number_nodes set to 1, and with the output values
node_id_list and node_uv_list allocated to a size of 1. The sgm_node_of_surface() function
should return with a return value of 9999 and the output value number_nodes_found will be
set to the number of nodes found on the list of surfaces.
The complete node list can then be obtained by calling the sgm_node_of_surface() function
with the input value init_flag set to 1. Continue calling the sgm_node_of_surface() function
until it no longer returns a value of 9999, indicating that all of the node identifiers have been
retrieved.
Example:
Please see sgm_node_on_surface (p. 1120) in the MSC.Acumen, Volume 2: Code Examples.

sgm_show_surface_normals ( surflist, scaled, numsurf, segid, redflag, vecdens,


veclen )

Description:
Routine that calculates and shows the surface normals.
Input:
STRING surflist[] The list of surfaces.
LOGICAL scaled TRUE if user wants to scale the normals to a percentage of
the surface area, FALSE otherwise.
INTEGER numsurf The number of surfaces (or segments).
INTEGER segid The ID of the segment.
INTEGER redflag 0 to show vectors on the interior and boundary, 1 to show
vectors on the boundary only.
INTEGER vecdens The number of vectors in the u and v directions.
REAL veclen The length of the vectors if they are not scaled.
Output:
INTEGER <Return Value> 0 if successful, else returns error code.
Main Index
CHAPTER 7 179
Geometry

Error Conditions:
14000010 In the list being used, the current sublist does not match the sublist filter.
14000015 LpSublistNext: End of current list has been reached.
1000025 Error attempting to allocate virtual memory.
1000707 No surfaces were found to exist in the database as defined in the surface list. The
surface list input was %A%.
Example:
Please see sgm_show_surface_normals (p. 1123) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_surface_evaluate (surface_data, ui, vi, derivative_use, surface_info, error_code )

Description:
This function evaluates a surface, returning information that defines the characteristics of a
surface.
Input:
REAL surface_data() This value specifies a surface data table or a blob. See the
remarks below for more information.
REAL ui This value specifies a parametric coordinate.
REAL vi This value specifies a parametric coordinate.
INTEGER derivative_use This value specifies the type of information that will be
returned by this function. See below for more
information.
Output:
REAL surface_info(21) This value returns the evaluated surface information. See
the remarks below for information on how to interpret the
values returned.
INTEGER error_code This value returns an error code and will be set to 0 if the
surface evaluation was successful and a non zero value to
indicate an error.
Error Conditions:
This is only a partial list of the error values that can be returned by this function.
1 A malformed surface data table or blob has been found. This problem is most
likely caused by an error in the input value surface_data.
2 This value indicates that the input value drivative_use has been set to request
normal information and that the current input values for ui and vi fall on an
unresolvable singularity. All of the other return vectors are valid at this point.
Only the normal vector is not to be used.
Remarks:
The size of the input value surface_data can be obtained with a call to the function
sgm_db_get_blob_size (p. 144). The surface data table or blob information can then be
retrieved with a call to sgm_db_get_surface (p. 175).
The input value derivative_use specifies the type of information that will be returned. The
following table explains the allowed values.
derivative_use valueInformation Returned
0 x, y, z
Main Index
180
Function Descriptions

1 x,y,z,nx,ny,nz,xu,yu,zu,xv,yv,zv
2 x,y,z,nx,ny,nz,xu,yu,zu,xv,yv,zv,xuu,yuu,zuu, xvv,yvv,zvv
3 x,y,z,nx,ny,nz,xu,yu,zu,xv,yv,zv,xuu,yuu,zuu, xvv,yvv,zvv,xuv,yuv,zuv
Example:
Please see sgm_surface_evaluate (p. 1126) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 7 181
Geometry

7.5 Solid

db_count_solid ( count )

Description:
Counts all solids in the database.
Input:
none
Output:
INTEGER count The integer number of solids in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_count_solid (p. 1018) in the MSC.Acumen, Volume 2: Code Examples.

db_get_max_solid_label ( label )

Description:
Gets the largest solid label from the database.
Input:
none
Output:
INTEGER label Highest solid label used.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Example:
Please see db_get_max_solid_label (p. 1033) in the MSC.Acumen, Volume 2: Code Examples.

db_get_min_solid_label ( label )

Description:
Gets the smallest solid label from the database.
Input:
none
Output:
INTEGER label Lowest solid label used.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Example:
Please see db_get_min_solid_label (p. 1037) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
182
Function Descriptions

db_get_solid_coo_and_type ( id, coo, type )

Description:
Gets a geometric coo and type from the database given an id.
Input:
INTEGER id The unique internal solid id identifying the association of the
information to be retrieved from the database.
Output:
INTEGER coo The geometric company of origin stored in the database.
INTEGER type The geometric type of data stored in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Example:
Please see db_get_solid_coo_and_type (p. 1044) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_solid_id ( label, id )

Description:
Gets a solid id from the database given a solid label.
Input:
INTEGER label The unique external solid id identifying the solid to be
retrieved from the database.
Output:
INTEGER id The unique internal solid id identifying the solid retrieved
from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Example:
Please see db_get_solid_id (p. 1045) in the MSC.Acumen, Volume 2: Code Examples.

db_get_solid_label ( id, label )

Description:
Gets a solid label from the database given a solid id.
Input:
INTEGER id The unique internal solid id identifying the solid to be
retrieved from the database.
Output:
INTEGER label The unique external solid id identifying the solid to be
retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Example:

Main Index
Please see db_get_solid_label (p. 1046) in the MSC.Acumen, Volume 2: Code Examples.
CHAPTER 7 183
Geometry

Main Index
184
Function Descriptions

asm_db_get_next_hpat_label ( domessage, integerlabel, stringlabel )

Description:
Get the next unused hpat label from the database.
Input:
LOGICAL domessage Tells the routine to issue an error message if an error
occurs.
Output:
INTEGER integerlabel The next highest solid label.
STRING stringlabel[] The next highest solid label.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see asm_db_get_next_hpat_label (p. 1007) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_construct_solid_brep (output_ids, surface_list, delete_flag, created_ids)

Description:
This function creates a b-rep solids from surfaces.
Input:
STRING output_ids[] The output ids to be assigned to the new solids.
STRING surface_list[] This value specifies the list of the surfaces used to create
the b-rep solid.
LOGICAL delete_flag This value is set to TRUE if the original surfaces are to be
deleted.
Output:
STRING created_ids[] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see sgm_construct_solid_brep (p. 1055) in the MSC.Acumen, Volume 2: Code Examples.

sgm_construct_solid_volume (output_ids, surface_list, delete_flag, created_ids)

Description:
This function creates solids with a set of surfaces.
Input:
STRING output_ids[ ] The output ids to be assigned to the new solids.
STRING surface_list[ ] This value specifies the list of the surfaces from which the
solid is to be created.
Main Index
CHAPTER 7 185
Geometry

LOGICAL delete_flag This value is set to TRUE if the original surfaces are to be
deleted.
Output:
STRING created_ids[] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see sgm_construct_solid_volume (p. 1056) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_db_get_num_vertices_body ( bodyid, numvert, status )

Description:
Gets the number of vertices for a general body.
Input:
INTEGER bodyid The ID of the body.
Output:
INTEGER numvert The number of vertices for the body.
INTEGER status Success or an error code.
Example:
Please see sgm_db_get_num_vertices_body (p. 1085) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_db_get_solid ( solidid, blobsize, blob, status )

Description:
Get the geometric definition of a solid from the database.
Input:
INTEGER solidid Id of the solid.
INTEGER blobsize The size of the blob in words.
Output:
REAL blob ( ) Array to be filled in with Geometric descriptionof a solid
as a blob.
INTEGER status 0: no error.
-1: database error.
-2: insufficient array length for the blob.
Error Conditions:
38000001 The allocated space for the blob is too small.
Example:
Please see sgm_db_get_solid (p. 1087) in the MSC.Acumen, Volume 2: Code Examples.
Main Index
186
Function Descriptions

sgm_edit_brep_break_plane_v1 (output_ids, solid_list, plane_list, delete_flag,


created_ids)
Description
:
This function breaks a set of solids with a set of planes.
Input:
STRING output_ids[ ] The output ids to be assigned to the new solids.
STRING solid_list[ ] This value specifies the list of the solids to be broken.
STRING plane_list[ ] This value specifies the list of the planes which will break
the solids.
LOGICAL delete_flag This value is set to TRUE if the original solids are to be
deleted.
Output:
STRING created_ids[ ] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see sgm_edit_brep_break_plane_v1 (p. 1091) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_edit_brep_break_surface_v1 (output_ids, solid_list, surface_list, delete_flag,


created_ids)
Description:
This function breaks a set of solids with a set of surfaces.
Input:
STRING output_ids[] The output ids to be assigned to the new solids.
STRING solid_list[] This value specifies the list of the solids to be broken.
STRING surface_list[] This value specifies the list of the surfaces which will
break the solids.
LOGICAL delete_flag This value is set to TRUE if the original solids are to be
deleted.
Output:
STRING created_ids[] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see sgm_edit_brep_break_surface_v1 (p. 1092) in the MSC.Acumen, Volume 2: Code
Examples.
Main Index
CHAPTER 7 187
Geometry

sgm_edit_solid_break (output_ids, option_type, point_list, parameter, delete_flag,


solid_list, created_ids)
Description:
This function breaks solids at a point or by parametric location.
Input:
STRING output_ids[] The output ids to be assigned to the new solids.
INTEGER option_type The option for breaking the solid
1 for breaking by point
0 for breaking by u,v, w parameters.
STRING point_list[] The point where the solid is to be broken if
option_type=1.
REAL ARRAY parameter(3) The u,v and w parameters if option_type = 0, 0<u,v,w<1
LOGICAL delete_flag This value is set to TRUE if the original solids are to be
deleted.
STRING solid_list[] List of solids to break.

Output:
STRING created_ids[] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_edit_solid_break (p. 1094) in the MSC.Acumen, Volume 2: Code Examples.

sgm_edit_solid_refit_v1 (output_ids, tolerance, type_option, delete_flag, solid_list,


created_ids)
Description:
This function edits solids for changing the topology.
Input:
STRING output_ids[] The output ids to be assigned to the new solids.
REAL tolerance This tolerance for fitting the solid.
LOGICAL type_option = TRUE for creating hyperpatches
= FALSE for creating a triparametric net
LOGICAL delete_flag This value is set to TRUE if the original solids are to be
deleted.
STRING solid_list[] The list of solids to refit.
Output:
STRING created_ids[] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
Main Index
188
Function Descriptions

See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_edit_solid_refit_v1 (p. 1096) in the MSC.Acumen, Volume 2: Code Examples.

sgm_edit_solid_reverse (solid_list, created_ids)

Description:
This function reverses the parametric directions of solids.
Input:
STRING solid_list[] List of solids to be reversed.
Output:
STRING created_ids[] This value returns the created ID list.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see sgm_edit_solid_reverse (p. 1097) in the MSC.Acumen, Volume 2: Code Examples.

sgm_get_solid_volume ( solid, volume )

Description:
Gets the volume of a solid.
Input:
INTEGER solid The ID of the solid.
Output:
REAL volume The volume of the solid.
INTEGER <Return Value> Success or an error code.
Error Conditions:
1000025 Error attempting to allocate virtual memory.
Example:
Please see sgm_get_solid_volume (p. 1109) in the MSC.Acumen, Volume 2: Code Examples.

sgm_solid_evaluate ( s, ui, vi, wi, in, pd, irc )

Description:
This subroutine plays traffic cop for the lower level solid evaluators.
Input:
REAL s() Solid data table.
REAL ui Parametric coordinates.
REAL vi Parametric coordinates.
Main Index
CHAPTER 7 189
Geometry

REAL wi Parametric coordinates.


INTEGER in Derivative flag.
0-P
1 - P,PU,PV,PW
2 - P,PU,PV,PW,PUV,PUW,PVW
3 - P,PU,PV,PW,PUV,PUW,PVW,PUU,PVV,PWW
Output:
REAL pd ( ,3) Output table (controlled by IN).
INTEGER irc 0 - evaluation successful.
1 - error somewhere, don’t trust the result.
Example:
See example for sgm_db_get_solid (p. 185). See also sgm_solid_evaluate (p. 1124) in the
MSC.Acumen, Volume 2: Code Examples.

sgm_verify_solid_brep ( surface list, verify_tol )

Description:
This function verifies that a collection of surfaces represent a valid B-rep solid.
Input:
STRING surface_list[] This value specifies the collection of surfaces that
represent the B-rep solid.
REAL verify_tol This value specifies a tolerance value used to determine if
the surfaces represent the B-rep solid. This value must be
less than or equal to the global geometric modeling
tolerance value.
Output:
INTEGER <Return Value> 0 if the function was successful.
Example:
Please see sgm_verify_solid_brep (p. 1128) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
190
Function Descriptions

7.6 Coordinate Frame

app_db_get_ref_cid ( domesg, cord_frame )

Description:
Get the default reference coordinate frame from the database.
Input:
LOGICAL domesg Error message flag: If TRUE, this routine will allow the
app_db_err_msg routine to issue a message if an error is
encountered.
Output:
STRING cord_frame[] The default reference coordinate frame.
INTEGER <Return Value> Success or an error code.
Example:
Please see app_db_get_ref_cid (p. 996) in the MSC.Acumen, Volume 2: Code Examples.

asm_u_coord_local_to_global ( p, t, r, itype, npts )

Description:
This function transforms points from local coordinates to global. It passes the transpose of the
rotation matrix stored in the database.
Input:
REAL ARRAYp(3,npts) The point coordinates in local frame.
REAL ARRAYt(3) This value specifies the translation vector for the global
coordinate frame.
REAL ARRAYr(3,3) This value specifies the rotation matrix for the global
coordinate frame and is the transpose of the rotation matrix
stored in the database.
INTEGER itype The reference coordinate frame type:
1=rectangular
2=cylindrical
3=spherical
INTEGER npts The number of points.
Output:
REAL ARRAYp(3,npts) The point coordinates in global frame.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this
function.
Example:
Please see asm_u_coord_local_to_global (p. 1010) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 7 191
Geometry

db_check_coord_frame_exist ( id )

Description:
Checks to see if a coordinate frame exists in the database.
Input:
INTEGER id The unique internal cid identifying the coordinate frame
to be retrieved from the database.
Output:
LOGICAL <Return Value> True if the cid exists.
Error Conditions:
This routine returns only a logical value, and gives no indication of why a failure occurred.
External Dependencies and Side Effects:
Accesses one record in the “coordinate_frame” table in the database.
Example:
Please see db_check_coord_frame_exist (p. 1014) in the MSC.Acumen, Volume 2: Code
Examples.

db_count_coordinate_frame ( count )

Description:
Counts all coordinate_frames in the database.
Input:
none
Output:
INTEGER count The integer number of coordinate_frames in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000002 Unrecoverable database error
External Dependencies and Side Effects:
Queries “coordinate_frame” table in the database.
Example:
Please see db_count_coordinate_frame (p. 1015) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_all_coord_frame_ids ( )

Description:
This function will set a cursor to the start of a list of all coordinate frames.
Input:
none
Output:
none
Main Index
192
Function Descriptions

Remarks:
This function must be called before the db_get_next_coord_frame_ids() function can be called.
Example:
Please see db_get_all_coord_frame_ids (p. 1021) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_next_coord_frame_ids ( id )

Description:
This function will get the next coordinate frame id from the database.
Input:
none
Output:
INTEGER id This value returns the id of the next coordinate frame id.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Remarks:
The PCL function db_get_all_coord_frame_ids() must be called at least once to establish the list
of posted coordinate frame id values and to set the cursor to point to the start of the list. Calling
the db_get_next_coord_frame_ids() function in a loop will then allow the list entries to be
retrieved.
Error Conditions:
13000002 Unrecoverable database error
13000007 An unspecified database error occurred.
13000085 Cursor not open.
13000117 The query specified has completed.
External Dependencies and Side Effects:
Accesses all records in the “coordinate frame” table in the database.
Example:
See example for db_get_all_coord_frame_ids (p. 191). See also
db_get_next_coord_frame_ids (p. 1038) in the MSC.Acumen, Volume 2: Code Examples.

db_get_max_coord_label ( label )

Description:
Gets the largest coord label from the database.
Input:
none
Output:
INTEGER label Highest coord label used.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Main Index
CHAPTER 7 193
Geometry

Error Conditions:
13000056 Coordinate frame not found.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Selects the largest coord label from the database.
Example:
Please see db_get_max_coord_label (p. 1031) in the MSC.Acumen, Volume 2: Code Examples.

db_get_min_coord_label ( label )

Description:
Gets the smallest coord label from the database.
Input:
none
Output:
INTEGER label Lowest coord label used.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000056 Coordinate frame not found.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Selects the smallest coord label from the database.
Example:
Please see db_get_min_coord_label (p. 1034) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_posted_coord ( )

Description:
This function will set a cursor to the start of a list of posted coordinate frames.
Input:
none
Output:
none
Remarks:
This function must be called before the db_get_next_posted_coord() function can be called.
Example:
Please see db_get_all_posted_coord (p. 1023) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
194
Function Descriptions

db_get_next_posted_coord ( id )

Description:
This function will get the next posted coordinate frame id from the database.
Input:
none
Output:
INTEGER id This value returns the id of the next posted coordinate
frame id.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Remarks:
The PCL function db_get_all_posted_coord() must be called at least once to establish the list of
posted coordinate frame id values and to set the cursor to point to the start of the list. Calling
the db_get_next_posted_coord() function in a loop will then allow the list entries to be
retrieved.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
13000085 Cursor not open.
13000117 The query specified has completed.
External Dependencies and Side Effects:
Accesses all records in the “coordinate frame” table in the database.
Example:
See example for db_get_all_posted_coord (p. 193). See also db_get_next_posted_coord
(p. 1039) in the MSC.Acumen, Volume 2: Code Examples.

asm_db_get_next_cord_label ( domessage, integerlabel, stringlabel )

Description:
Get the next highest coord label from the database.
Input:
LOGICAL domessage Tells the routine to issue an error message if an error
occurs.
Output:
INTEGER integerlabel The next highest coord label.
STRING stringlabel[] The next highest coord label.
INTEGER <Return Value> Success or an error code.
Example:
Please see asm_db_get_next_cord_label (p. 1004) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 7 195
Geometry

db_get_coord_frame_label ( id, label )

Description:
Gets a label from the database given an id.
Input:
INTEGER id The unique internal id identifying the coord to be
retrieved from the database.
Output:
INTEGER label The unique external id identifying the coord to be
retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Accesses one record in the “coordinate_frame” table in the database.
Example:
Please see db_get_coord_frame_label (p. 1024) in the MSC.Acumen, Volume 2: Code Examples.

db_get_current_coord ( coord_label )

Description:
Retrieves the current coordinate frame from the database.
Input:
none
Output:
INTEGER label Location for returned value.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000056 Coordinate frame not found
13000007 An unspecified database error occurred.
Example:
Please see db_get_current_coord (p. 1025) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
196
Function Descriptions

7.7 Point/Curve Relation

db_count_curves_for_point ( id, count )

Description:
Counts all curves associated with a specified point in the database.
Input:
INTEGER id The id of the point to which the curves are associated.
Output:
INTEGER count The integer number of curves associated to the point in the
database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000097 Curve input was not found.
Example:
Please see db_count_curves_for_point (p. 1016) in the MSC.Acumen, Volume 2: Code Examples.

db_get_curves_for_point ( ptid,count,crvid)

Description:
Finds the ids of all curves associated with a specified point in the database.
Input:
INTEGER ptid Id of the point to which the curves are associated.
INTEGER count The number of curves that the calling routine expects to
receive from the database. This count should be the same as
the number of curves to which the point is associated as it
should have been fetched from the database prior to making
this call.
Output:
INTEGER crvid() Ids of the various curves associated with the specified point.
Example:
See example for db_count_curves_for_point (p. 196). See also db_get_curves_for_point
(p. 1028) in the MSC.Acumen, Volume 2: Code Examples.

sgm_db_get_edge_vertex_ids ( edgeid, vertexids )

Description:
This function returns the vertex id values foran edge.
Input:
INTEGER edgeid This value specifies the id of an edge.

Main Index
CHAPTER 7 197
Geometry

Output:
INTEGER vertexids ( ) This value returns the id values of the vertices of an edge.
INTEGER <Return Value> 0 if the function was successful.
Example:
Please see sgm_db_get_edge_vertex_ids (p. 1075) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_nearest_point_on_curve (location, curve_data, parameter, point_location)

Description:
This function gets the nearest point at a specific parametric location on a curve.
Input:
REAL location(3) The xyz location of the point in space.
ARRAY
REAL curve_data() The blob of the curve. The functions to be used for get-
ARRAY ting the blob are sgm_db_get_blob_size() followed by
sgm_db_get_curve().
REAL parameter The parameter value along the curve where to look for
the nearest point.
Output:
REAL point_location(3) The xyz location of the nearest point in space.
ARRAY
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_nearest_point_on_curve (p. 1114) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_nearest_point_on_curve_aea (location, curve_data, parameter, point_location)

Description:
This function gets the nearest point at a specific parametric location on a curve.
Input:
REAL ARRAY location(3) The xyz location of the point in space.
REAL ARRAY curve_data() The blob of the curve. The functions to be used for get-
ting the blob are sgm_db_get_blob_size() followed by
sgm_db_get_curve().
REAL parameter The parameter value where to look for the nearest point.
Output:
REAL ARRAY point_location(3) The xyz location of the nearest point in space.
INTEGER <Return_value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
Main Index
198
Function Descriptions

See the Status Messages (Ch. 11) for information on any error values returned by this function.
Example:
Please see sgm_nearest_point_on_curve_aea (p. 1115) in the MSC.Acumen, Volume 2: Code
Examples.

xy_curve_num_points_get (<curve_name>,<yonly>,<npoints>)

Description:
This function will get the number of points on the curve.
Input:
STRING curve_name Name of the curve.
Output:
LOGICAL yonly Flag which is TRUE if curve uses only y values and FALSE
if curve uses both xy values.
INTEGER npoints Number of points on the curve.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
See the Status Message(Ch 11) for information on any error values returned by this function.
Example:
Please see xy_curve_num_points_get (p. 1130) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 7 199
Geometry

7.8 Curve/Surface Relation

db_count_surfaces_for_edge ( id, count )

Description:
Counts all surfaces associated with a specified edge in the database.
Input:
INTEGER id The id of the edge to which the surfaces are associated.
Output:
INTEGER count The integer number of surfaces associated to the edge in
the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
See example for db_count_surface (p. 170). See also db_count_surfaces_for_edge (p. 1020)
in the MSC.Acumen, Volume 2: Code Examples.

db_get_surfaces_for_edge ( edgid, count, srfid )

Description:
Finds the ids of all surfaces associated with a specified edge in the database.
Input:
INTEGER edgid Id of the edge to which the surfaces are associated.
INTEGER count The number of surfaces that the calling routine expects to
receive from the database. This count should be the same
as the number of surfaces to which the edge is associated
as it should have been fetched from the database prior to
making this call.
Output:
INTEGER srfid() Ids of the various surfaces associated with the specified
edge.
Example:
See example for db_count_surface (p. 170). See also db_get_surfaces_for_edge (p. 1051) in
the MSC.Acumen, Volume 2: Code Examples.

sgm_db_get_gen_face_edge_ids ( surfaceid, numberloops, numberedges, loopids,


edgeids, edgeorients )

Description:
Returns the loop ids, edge ids, and orientations for an n-sided surface identified by its id.
Input:
INTEGER surfaceid The id of the surface.
Main Index
200
Function Descriptions

INTEGER numberloops Total number of loops for the surface.


INTEGER numberedges The total number of edges for the surface.
Output:
INTEGER loopids ( ) The loop handle for each edge. (dim
totalNumberOfEdges).
INTEGER edgeids ( ) The ids of the edge. (dim totalNumberOfEdges).
INTEGER edgeorients ( ) The orientations of the edge. (dim totalNumberOfEdges).
INTEGER <Return Value> Success or an error code.
Example:
See example for sgm_db_get_num_loops_face (p. 175). Please see
sgm_db_get_gen_face_edge_ids (p. 1079) in the MSC.Acumen, Volume 2: Code Examples.

sgm_db_get_gen_face_vertex_ids ( surfaceid, numberverts, vertexids )

Description:
Returns the vertex ids for an n-sided surface identified by its id.
Input:
INTEGER surfaceid The id of the surface.
INTEGER numberverts The number of vertices for the surface.
Output:
INTEGER vertexids ( ) The ids of the vertex.
INTEGER <Return Value> Success or an error code.
Example:
Please see sgm_db_get_gen_face_vertex_ids (p. 1080) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_db_get_num_edges_face ( surfaceid, numberfaces )

Description:
This function will return the number of edges of the specified surface.
Input:
INTEGER surfaceid This value specifies the identifier for a surface or the face
of a solid.
Output:
INTEGER numberfaces This value returns the number of edges of the specified
surface of face of a solid.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Example:
See example for sgm_db_get_num_loops_face (p. 175). See also
sgm_db_get_num_edges_face (p. 1081) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 7 201
Geometry

7.9 Surface/Solid Relation

db_count_solids_for_surface ( id, count )

Description:
Counts all solids associated with a specified surface in the database.
Input:
INTEGER id The id of the surface to which the solids are associated.
Output:
INTEGER count The integer number of solids associated to the surface in
the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_count_solids_for_surface (p. 1019) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_solids_for_surface ( srfid, count, solid )

Description:
Finds the ids of all solids associated with a specified surface in the database.
Input:
INTEGER srfid Id of the surface to which the solids are associated.
INTEGER count The number of solids that the calling routine expects to
receive from the database. This count should be the same
as the number of solids to which the surface is associated
as it should have been fetched from the database prior to
making this call.
Output:
INTEGER solid() Ids of the various solids associated with the specified
surface.
Example:
Please see db_get_solids_for_surface (p. 1047) in the MSC.Acumen, Volume 2: Code Examples.

sgm_db_get_gen_body_face_ids ( bodyid, numberfaces, faceids, faceorients,


facesense, status )

Description:
Gets the Face IDs for a body.
Input:
INTEGER bodyid The ID of the body.
INTEGER numberfaces The number of face for the body.
Main Index
202
Function Descriptions

Output:
INTEGER faceids () The IDs of the faces of the body.
INTEGER faceorients ( ) The orientations of the faces of the body.
INTEGER facesense ( ) The sense of the normal (out or in).
INTEGER status Success or an error code.
Example:
See example for sgm_db_get_num_loops_face (p. 175). See also
sgm_db_get_gen_body_face_ids (p. 1076) in the MSC.Acumen, Volume 2: Code Examples.
Notes:
The faceorients () values listed above provide the following information:
The surface normal relative to position 0 (where the face exactly matches the underlying
surface).
The offset according to the INDUSTRY STANDARD, not according to MSC.Patran standards.
Note that the offset is always given relative to position 0 when the face exactly matches the
topology of the underlying surface.

Value Orientation Face Sense Offset

0 DB_FACE_ORIENTATION_POS0 DB_FACE_SENSE_POSITIVE DB_GEN_FACE_POS0

1 DB_FACE_ORIENTATION_POS1 DB_FACE_SENSE_NEGATIVE DB_GEN_FACE_POS0

2 DB_FACE_ORIENTATION_POS2 DB_FACE_SENSE_NEGATIVE DB_GEN_FACE_POS3

3 DB_FACE_ORIENTATION_POS3 DB_FACE_SENSE_POSITIVE DB_GEN_FACE_POS1

4 DB_FACE_ORIENTATION_POS4 DB_FACE_SENSE_NEGATIVE DB_GEN_FACE_POS2

5 DB_FACE_ORIENTATION_POS5 DB_FACE_SENSE_POSITIVE DB_GEN_FACE_POS2

6 DB_FACE_ORIENTATION_POS6 DB_FACE_SENSE_POSITIVE DB_GEN_FACE_POS3

7 DB_FACE_ORIENTATION_POS7 DB_FACE_SENSE_NEGATIVE DB_GEN_FACE_POS1

Reverse pairs (If you reverse a 4-sided surface as the orientation toggles between these two
values.

DB_FACE_ORIENTATION_POS0 <-> DB_FACE_ORIENTATION_POS0


DB_FACE_ORIENTATION_POS2 <-> DB_FACE_ORIENTATION_POS6
DB_FACE_ORIENTATION_POS3 <-> DB_FACE_ORIENTATION_POS7
DB_FACE_ORIENTATION_POS4 <-> DB_FACE_ORIENTATION_POS8

sgm_db_get_gen_body_vertex_ids ( bodyid, numvert, vertexids, status )

Description:
Gets the Vertex IDs for a body.
Input:
Main Index
CHAPTER 7 203
Geometry

INTEGER bodyid The ID of the body.


INTEGER numvert The number of vertices for the body.
Output:
INTEGER vertexids ( ) The IDs of the vertices of the body.
INTEGER status 0 if successful, error code otherwise.
Example:
Please see sgm_db_get_gen_body_vertex_ids (p. 1078) in the MSC.Acumen, Volume 2: Code
Examples.

sgm_db_get_num_faces_body ( bodyid, numberfaces, status )

Description:
Gets the number of faces for a general body.
Input:
INTEGER bodyid The ID of the body.
Output:
INTEGER numberfaces The number of faces for the body.
INTEGER status 0 if successful, else returns error code.
Example:
See example for sgm_db_get_num_loops_face (p. 175). See also
sgm_db_get_num_faces_body (p. 1082) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
204
Function Descriptions

7.10 Transform

transform_pts ( cid, cidtyp, npts, points )

Description:
This function will transform points defined in the global coordinate system to the specified
local coordinate system.
Input:
INTEGER cid This value specifies the local coordinate system id.
INTEGER npts This value specifies the number of points to be
transformed.
REAL points(3,npts) This value specifies the coordinates of the points to be
transformed. This value is used as both an input and an
output to this function and the values passed into the
function will be changed.
Output:
INTEGER cidtyp This value returns the type of the local coordinate system.
REAL points (3,npts) This value returns the coordinates of the points
transformed into the local coordinate system. This value
is used as both an input and an output to this function.
The original input values for this array will be lost.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Example:
Please see transform_pts (p. 1129) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Finite Element Model
8
■ Finite Elements
■ MPCs
■ Nodes
■ Mesh

■ Element/Node Relations

Main Index
204
Function Descriptions

8.1 Finite Elements

db_get_next_elem_id (id)

Description:
This function will return the next available element ID to the caller.
Input:
None.
Output:
INTEGER id The next available element ID.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_get_next_elem_id (p. 1166) in the MSC.Acumen, Volume 2: Code Examples.

db_get_min_elem_id (id)

Description:
This function will search the entire element list to find the minimum element ID currently in
use.
Input:
None.
Output:
INTEGER id The minimum element ID currently in use.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_get_min_elem_id (p. 1163) in the MSC.Acumen, Volume 2: Code Examples.

db_get_max_elem_id (id)

Description:
This function will search the entire element list to find the maximum element ID currently in
use.
Input:
None.
Output:
INTEGER id The maximum element ID currently in use.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
See example for db_get_min_elem_id (p. 204). See also db_get_max_elem_id (p. 1160) in the
MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 8 205
Finite Element Model

fem_get_elem_assoc_groups (nelem, idelems, ngroups, ids)

Description:
Get a list of all the groups associated with the elements in the FEM_LIST
Input:
INTEGER nelem Number of elements.
INTEGER idelems() List of elements.
Output:
INTEGER ngroups Number of unique groups associated with elements.
INTEGER ids()symbol Pointer to VIRTUAL integer array containing list of
associated group IDs.
INTEGER <Return Value> 0 Function was successful.
-1 Abort
-2 No elements in list
-3 No associated groups
Error Conditions:
2001070 Unable to acquire %I% words of virtual memory.
4 Interrupted system call.
Example:
Please see fem_get_mpc_assoc_groups (p. 1184) in the MSC.Acumen, Volume 2: Code
Examples.

fem_get_elem_ids (entity_list, nelem, idelem, notfound, idnoexist)

Description:
Extract the array of existing element IDs from ELEM_LST.
Input:
STRING entity_list[] List of selected elements.
Output:
INTEGER nelem Number of existing element IDs.
INTEGER idelem()symbol Pointer to sorted Element IDs.
INTEGER notfound Number of elements that were not found.
INTEGER idnoexist()symbol Pointer to sorted list of nonexistent IDs.
INTEGER <Return Value> 0 Function was successful.
-1 Abort.
-2 No existing elements in list.
Example:
See example for fem_get_elem_assoc_groups (p. 205). See also fem_get_elem_ids
(p. 1183) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
206
Function Descriptions

fem_u_get_free_edges ( el_ids, max_nodes, max_per_edge, max_edges, nels,


el_con, el_shape, el_nodes, edge_el_ids, edge_ids,
free_edges )

Description:
Create a list of all free edges in a list of finite elements.
Input:
INTEGER el_ids() List of elements.
INTEGER max_nodes Maximum number of nodes per element in EL_IDS.
INTEGER max_per_edge Maximum number of nodes per edge in EL_IDS.
INTEGER max_edges Maximum number of edges per 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 edge_el_ids() Associated element id.
INTEGER edge_ids() Free edge ID.
INTEGER free_edges Number of free edges.
INTEGER <Return Value> 0, no error.
1, Unsupported element type (shape/nodes).
2, Memory allocation error.
Example:
Please see fem_u_get_free_edges (p. 1190) in the MSC.Acumen, Volume 2: Code Examples.

fem_u_get_free_faces (el_ids, max_nodes, max_per_face, max_faces, num_els,


el_con, el_shape, el_nodes, face_el_ids, face_ids, free_faces)

Description:
This function will create a list of all free element faces in a list of solid finite elements.
Input:
INTEGER el_ids(num_els) This value specifies a list of solid element identifiers.
INTEGER max_nodes This value specifies the maximum number of nodes used
by the elements specified by the input value el_ids.
INTEGER max_per_face This value specifies the maximum number of nodes used
by the elements specified by the input value el_ids.
INTEGER max_faces This value specifies the maximum number of faces used
by the elements specified by the input value el_ids.
INTEGER num_els This value specifies the number of offsets defined for the
input value el_ids.
INTEGER el_con(num_els * max_nodes)
This value specifies the solid element connectivity node
list.
INTEGER el_shape(num_els) This value specifies the shapes of the solid elements.
INTEGER el_nodes(num_els) This value specifies the solid element node counts.
Main Index
CHAPTER 8 207
Finite Element Model

Output:
INTEGER face_el_ids(max_per_face * num_els)
This value returns the associated element identifiers.
INTEGER face_ids(max_per_face * num_els)
This value returns the free face identifiers.
INTEGER free_faces This value returns the number of free faces.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
This is only a partial list of the error values that can be returned by this function.
1 An unsupported element shape or node type has been specified.
2 A memory allocation error has occurred.
Example:
Please see fem_u_get_free_faces (p. 1192) in the MSC.Acumen, Volume 2: Code Examples.

db_update_elem_ids (numelem, old_id, new_id)

Description:
This function changes the ID of a list of elements.
Input:
INTEGER numelem The number of elements to be changed.
INTEGER old_id() The list of old element IDs.
INTEGER new_id() The list of new element IDs.
Output:
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
0 Successful Completion.
13000095 User Aborted Transaction In Progress.
13000118 The renumber specified could not complete.
Example:
Please see db_update_elem_ids (p. 1176) in the MSC.Acumen, Volume 2: Code Examples.

db_count_elems_for_geo (geo_type, geo_id, nbr_of_elements)

Description:
Count the number of elements that have the given geometry type and ID.
Input:
INTEGER geo_type The geometry type to search for.
INTEGER geo_id The geometry ID to search for.
Output:
INTEGER nbr_of_elements The number of elements found.
INTEGER <Return Value> Returns the success or failure of the routine.
Main Index
208
Function Descriptions

Error Conditions:
SUCCESS This function completed successfully.
13000041 Element not found .
Example:
Please see db_count_elems_for_geo (p. 1135) in the MSC.Acumen, Volume 2: Code Examples.

db_update_elem_types (nelem, mxnode, eid, etop, econ)

Description:
This function will update the given elements with the new element topology and create a set of
new nodes for that element.
Input:
INTEGER nelem The number of elements to be created.
INTEGER mxnode The number of nodes on each element.
INTEGER eid() The array of element IDs to be used.
INTEGER etop() The array of element topologies to be used.
INTEGER econ() The array of node IDs for each element.
Output:
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
SUCCESS This function completed successfully.
Example:
Please see db_update_elem_types (p. 1178) in the MSC.Acumen, Volume 2: Code Examples.

db_count_elem_topology_codes (ntop)

Description:
This function will count the total number of element topologies currently defined in the system.
Input:
None.
Output:
INTEGER ntop The number of element topologies in the database.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_count_elem_topology_codes (p. 1134) in the MSC.Acumen, Volume 2: Code
Examples.

db_count_elem_w_topology (ntop, top, nelem)

Description:
This function will count the number of elements that have the specified topologies. The
maximum number of topologies that can be returned is passed in by the caller and the caller
passes in the address of the output array.
Main Index
CHAPTER 8 209
Finite Element Model

Input:
INTEGER ntop The number of topologies to be looked up.
INTEGER top() An array of the topologies to look up.
Output:
INTEGER nelem() An array of the number of elements of each type.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
See example for db_count_elem_w_topology (p. 208). See also db_count_elem_w_topology
(p. 1134) in the MSC.Acumen, Volume 2: Code Examples.

db_count_nodes_for_geometry (geoType, geoId, parentType, parentId, nodeCount)

Description:
This function will count all of the nodes associated with the specified piece of geometry. If the
parent geometry parameters are specified, then the given child geometry is assumed to be a
constituent part of the parent. The parent geometry and ID must define the entity that contains
the elements that the requested nodes belong to. For example, if the caller wants all of the nodes
on an edge of a solid, the “geoType” and “geoId” should refer to the specific edge and the
“parentType” and “parentId” should refer to the solid (assuming that the desired nodes are
part of a solid mesh.)
Input:
INTEGER geoType The type of the geometry in question (point, curve, etc.)
INTEGER geoId The ID of the geometry in question.
INTEGER parentType The type of the highest order geometry that the
“geoType” is part of.
INTEGER parentId The ID of the highest order geometry that the “geoType”
is part of.
Output:
INTEGER nodeCount The number of nodes associated with that piece of
geometry.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_count_nodes_for_geometry (p. 1138) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_elems nelem, mxnode, eid, etop, gtype, gid, econ

Description:
This function will retrieve all of the information about a group of elements from the memory
database given the IDs of the elements. The user must pass in the addresses of the output
arrays.
Input:
INTEGER nelem The number of elements being requested.
INTEGER mxnode The maximum number of nodes allowed for each
element.
Main Index
210
Function Descriptions

INTEGER eid (nelem) An array to element IDs to be looked up.


Output:
INTEGER etop (nelem) An array of element topologies.
INTEGER gtype (nelem) An array of associated geometry types.
INTEGER gid (nelem) An array of associated geometry IDs.
INTEGER econ (nelem, mxnode) An array of nude IDs that belong to each element.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_get_elems (p. 1155) in the MSC.Acumen, Volume 2: Code Examples.

db_get_elems_by_lbc (lbc_id, max_elem, numelem, eid)

Description:
Gets all elements associated with a specified LBC.
Input:
INTEGER lbc_id Id of the LBC to which the requested elements are
associated.
INTEGER max_elem Maximum number of element IDs for which storage has
been allocated by the calling routine.
Output:
INTEGER nelem Number of elements found associated to the specified
LBC.
INTEGER eid() Ids of the elements associated to the specified lbc.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
None.
Example:
Please see db_get_elems_by_lbc (p. 1156) in the MSC.Acumen, Volume 2: Code Examples.

db_get_elem_config_ntl (atid, acid, geopcd, copcd, fopcd, lopcd, etopid, dofsetid,


matlcode, matdcode, config)

Description:
Gets an ntl 25 configuration code from the database.
Input:
INTEGER atid The id of the analysis type associated to the selected
element type.
INTEGER acid The id of the analysis code associated to the selected
element type.
INTEGER geopcd The id of the geometric option code associated with the
selected element type.

Main Index
CHAPTER 8 211
Finite Element Model

INTEGER copcd The id of the condense option code associated with the
selected element type.
INTEGER fopcd The id of the formulation option code associated with the
selected element type.
INTEGER lopcd The id of the laminate option code associated with the
selected element type.
INTEGER etopid The id of the element topology associated with the
selected element type.
INTEGER dofsetid The id of the degree of freedom associated with the
selected element type.
INTEGER matlcode The id of the material code associated with the selected
element type.
INTEGER matdcode The id of the material definition code associated with the
selected element type.
Output:
INTEGER config The id of the associated configuration.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Gets a record in the “selected_element_type” table.
Example:
Please see db_get_elem_config_ntl (p. 1147) in the MSC.Acumen, Volume 2: Code Examples.

db_get_elem_dimens (top_id, dimen)

Description:
This function will retrieve the element dimensionality for the specified element topology ID
value.
Input:
INTEGER top_id The element topology ID value.
Output:
INTEGER dimen The element dimensionality for the specified ID.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000041 Element not found.
External Dependencies and Side Effects:
None.
Example:
Please see db_get_elem_dimens (p. 1149) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
212
Function Descriptions

db_get_elem_for_geo_type_and_id (geo_type, geo_id, nbr_of_elements, element)

Description:
This function will retrieve all of the element IDs that have a given geometry type and geometry
ID.
Input:
INTEGER geo_type The desired geometry type to look for.
INTEGER geo_id The desired geometry ID to look for.
INTEGER nbr_of_elements The maximum number of elements we can return.
Output:
INTEGER element The array of element IDs with the specified type and ID.
(nbr_of_elements)
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000041 Element not found.
13000093 Too Many Values Returned for Space Allocated.
Example:
Please see db_get_elem_for_geo_type_and_id (p. 1149) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_elem_shape_for_id (nelem, eid, shape)

Description:
This function gets the shape codes for the array of elements specified.
Input:
INTEGER nelem The number of elements to be looked up.
INTEGER eid() The array of input element IDs.
Output:
INTEGER shape() The array of shape codes.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000041 Element not found.
SUCCESS This function completed successfully.
Example:
Please see db_get_elem_shape_for_id (p. 1151) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 8 213
Finite Element Model

db_get_elem_topology_codes (ntop, top)

Description:
The number of element topologies defined in the database.
Input:
INTEGER ntop The maximum number of topology IDs that can be
returned.
Output:
INTEGER top() The array of the element topology IDs.
INTEGER <Return Value> Integer indicating the success or failure of the routine.
Example:
Please see db_get_elem_topology_codes (p. 1153) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_elem_topos_for_geom (geo_id, geo_type, n_tops, top_ids)

Description:
This function will retrieve all of the distinct topology IDs currently in use that match the
specified geometry type and geometry ID.
Input:
INTEGER geo_id The desired geometry ID to look for.
INTEGER geo_type The desired geometry type to look for.
Output:
INTEGER n_tops The number of topologies that were found.
INTEGER top_ids() The array of topology IDs that were found.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_elem_topos_for_geom (p. 1153) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_elem_top_name (id, name)

Description:
This function will retrieve the element topology name for the specified element topology ID
value. Note: The output string that will hold the name of the degenerate element topology
MUST be at least GrNameLength bytes long. Anything less can cause memory to be
overwritten!
Input:
INTEGER id The element topology ID value.
Output:
STRING name[] The element topology name string.

Main Index
214
Function Descriptions

INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000091 Analysis type input was not found.
SUCCESS This function completed successfully.
Example:
Please see db_get_elem_top_name (p. 1152) in the MSC.Acumen, Volume 2: Code Examples.

db_get_elem_verification_parms (analysis_code_name, test_id, threshold)

Description:
Gets the element verification parameters.
Input:
STRING analysis_code_name[31] The current analysis code name.
INTEGER test_id The specific test id.
Output:
REAL threshold The threshold value.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000090 Analysis code input was not found.
13000086 No Records Found.
External Dependencies and Side Effects:
This routine accesses records in the analysis_code and element_verification_parms tables in the
database.
Example:
Please see db_get_elem_verification_parms (p. 1154) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_etop_for_a_code (acid, atid, count, etop)

Description:
Retrieves a set of element_topology_ids based of analysis code and type id.
Input:
INTEGER acid The analysis code id.
INTEGER atid The analysis type id.
INTEGER count Maximum number of topologies to be returned.
Output:
INTEGER etids() The element type ids retrieved.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Main Index
CHAPTER 8 215
Finite Element Model

Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Retrieves analysis_elements relationships.
Example:
Please see db_get_etop_for_a_code (p. 1158) in the MSC.Acumen, Volume 2: Code Examples.

db_get_indep_nodes_in_sub_mpc (mpc_id, sub_mpc_id, mxnode, nnode, nid)

Description:
This function returns a list of independent nodes which refer to the specified sub-MPC.
Input:
INTEGER mpc_id This value specifies the mass property constraint or
MPC id for which the information is being requested.
INTEGER sub_mpc_id This value specifies the sub-mass property constraint or
MPC id for which the information is being requested.
INTEGER mxnode This value specifies the maximum number of nodes
which may be returned for the sub-MPC. This value
should be less than or equal to the number of offsets
defined for the return value nid.
Output:
INTEGER nnode This value returns the number of nodes using the sub-
mass property constraint or MPC.
INTEGER nid() This value returns the id values of the nodes for each
sub-mass property constraint or MPC. The number of
offsets allocated for this array should be less than or
equal to the input value mxnode.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
13000142 The MPC was not found in the database.
13000143 The sub-MPC was not found in the database.
13000150 The list of nodes for one or more of the MPCs is longer than MAXNODE.
External Dependencies and Side Effects:
Accesses records in the mpc_term_node table in the database.
Example:
Please see db_get_indep_nodes_in_sub_mpc (p. 1159) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
216
Function Descriptions

8.2 MPCs

db_get_next_mpc_id ( next_id )

Description:
Return the next available unused MPC id.
Input:
None.
Output:
INTEGER next_id The MPC id.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000004 Duplicate entry exists in table.
External Dependencies and Side Effects:
Accesses records in the mpc table in the database.
Example:
Please see db_get_next_mpc_id (p. 1166) in the MSC.Acumen, Volume 2: Code Examples.

fem_get_mpc_assoc_nodes ( nmpc, idmpcs, nnodes, ids )

Description:
Get a list of all the nodes associated with the MPCs in the FEM_LIST.
Input:
INTEGER nmpc Number of MPCs.
INTEGER idmpcs(nmpc) List of MPCs.
Output:
INTEGER nnodes Number of unique nodes associated with MPCs.
INTEGER ids()symbol Pointer to VIRTUAL integer array containing list of
associated Node IDs.
INTEGER <Return Value> 0 Function was successful.
-1 Abort
-2 No MPCs in list
-3 No associated nodes
Error Conditions:
2001070 Unable to acquire %I% words of virtual memory.
4 Interrupted system call.
Example:
Please see fem_get_mpc_assoc_nodes (p. 1185) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 8 217
Finite Element Model

fem_get_mpc_ids ( entity_list, nmpc, idmpc, notfound, idnoexist )

Description:
This function will extract an array of MPC id values from a picklist string.
Input:
STRING entity_list[] This value specifies a list of mass property constraints or
MPCs.
Output:
INTEGER nmpc This value returns the number of offsets defined for the
return value idmpc.
INTEGER idmpc(VIRTUAL) This value returns the sorted mass property constraint
or MPC id values.
INTEGER notfound This value returns the number of offsets defined for the
return value idnoexist.
INTEGER idnoexist(VIRTUAL) This value returns the sorted id values for mass
property constraints or MPCs that do not exist.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
-1 Abort.
-2 No existing MPCs in list.
4 Interrupted system call.
2001070 Unable to acquire %I% words of virtual memory.
Example:
Please see fem_get_mpc_ids (p. 1186) in the MSC.Acumen, Volume 2: Code Examples.

db_count_valid_dofs_f_mpc_type ( mpc_type_id, num_dofs )

Description:
Gets a count of the valid degrees of freedom for a particular MPC types from the database.
Input:
INTEGER mpc_type_id The MPC type id
Output:
INTEGER inum_dofs The number of valid DOFS for this MPC type id.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
External Dependencies and Side Effects:
Accesses records in the mpc_term_dof table in the database.
Example:
Please seedb_count_valid_dofs_f_mpc_type (p. 1141) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
218
Function Descriptions

db_validate_mpc ( mpc_id, valid_flag )

Description:
This function determines if an MPC is valid.
Input:
INTEGER mpc_id This value specifies the MPC identifier.
Output:
LOGICAL valid_flag This value returns the status of the MPC. If this value is
set to 1 ( TRUE ), then the MPC is value. If this value is
set to 0 ( FALSE ) then the MPC is invalid.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
External Dependencies and Side Effects:
Accesses records in the mpc, valid_mpc_type, control_info and analysis_code tables in the
database.
Remarks:
An MPC is valid if its type and associated degrees of freedom are valid for the current analysis
code and analysis type preferences.
Example:
Please see db_validate_mpc (p. 1179) in the MSC.Acumen, Volume 2: Code Examples.

db_count_valid_mpc_types ( numtypes )

Description:
Gets a count of the valid MPC type for the default analysis type id and analysis code id from
the database.
Input:
None.
Output:
INTEGER numtypes The number of valid MPC type ids.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
External Dependencies and Side Effects:
Accesses records in the valid_mpc_type table in the database.
Example:
Please see db_count_valid_mpc_types (p. 1141) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 8 219
Finite Element Model

db_get_all_valid_dof_f_mpc_type ( mpc_type_id )

Description:
Get all the valid degrees of freedom for a particular MPC type from the database.
Input:
INTEGER mpc_type_id The MPC type id.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
See example for db_count_valid_dofs_f_mpc_type (p. 217). See also
db_get_all_valid_dof_f_mpc_type (p. 1142) in the MSC.Acumen, Volume 2: Code Examples.

db_get_nxt_valid_dof_f_mpc_type ( mpc_type_id, dof_id, dof_name )

Description:
Get the next valid degree of freedom for a particular MPC type from the database.
Input:
INTEGER mpc_type_id The MPC type id.
Output:
INTEGER dof_id The degree of freedom id.
STRING dof_name[] The degree of freedom name.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000142 The MPC was not found in the database.
External Dependencies and Side Effects:
Accesses records in the mpc_type, mpc and mpc_term_dof tables in the database.
Example:
See example for db_count_valid_dofs_f_mpc_type (p. 217). See also
db_get_nxt_valid_dof_f_mpc_type (p. 1173) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_valid_mpc_type ( )

Description:
Get the next valid (for the current analysis code and analysis type) MPC type id and name
stored in the database.
Input:
None.

Main Index
220
Function Descriptions

Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000142 The MPC was not found in the database.
External Dependencies and Side Effects:
Accesses records in the mpc_type, mpc and mpc_term_dof tables in the database.
Example:
See example for db_count_valid_mpc_types (p. 218). See also db_get_all_valid_mpc_type
(p. 1143) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_valid_mpc_type ( mpc_type_id, mpc_type_name )

Description:
Get the next valid (for the current analysis code and analysis type) MPC type id and name
stored in the database.
Input:
None.
Output:
INTEGER mpc_type_id The MPC type id.
STRING mpc_type_name[] The MPC type name.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000142 The MPC was not found in the database.
External Dependencies and Side Effects:
Accesses records in the valid_mpc_type and mpc_type table in the database.
Example:
See example for db_count_valid_mpc_types (p. 218). See also
db_get_next_valid_mpc_type (p. 1168) in the MSC.Acumen, Volume 2: Code Examples.

db_get_dep_nodes_in_sub_mpc ( mpc_id, sub_mpc_id, mxnode, nnode, nid )

Description:
This function returns a list of dependent nodes which refer to the specified sub-MPC.
Input:
INTEGER mpc_id This value specifies the mass property constraint or
MPC id for which the information is being requested.
INTEGER sub_mpc_id This value specifies the sub-mass property constraint or
MPC id for which the information is being requested.

Main Index
CHAPTER 8 221
Finite Element Model

INTEGER mxnode This value specifies the maximum number of nodes


which may be returned for the sub-MPC. This value
should be less than or equal to the number of offsets
defined for the return value nid.
Output:
INTEGER nnode This value returns the number of nodes using the sub-
mass property constraint or MPC.
INTEGER nid() This value returns the id values of the nodes for each
sub-mass property constraint or MPC. The number of
offsets allocated for this array should be less than or
equal to the input value mxnode.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
13000142 The MPC was not found in the database.
13000143 The sub-MPC was not found in the database.
13000150 The list of nodes for one or more of the MPCs is longer than MAXNODE.
External Dependencies and Side Effects:
Accesses records in the mpc_term_node table in the database.
Example:
Please see db_get_dep_nodes_in_sub_mpc (p. 1144) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_dof_id ( dof_name, dof_id )

Description:
Get the degree of freedom id from its degree of freedom name.
Input:
STRING dof_name[] The degree of freedom name.
Output:
INTEGER dof_id The degree of freedom id.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000140 The DOF ID was not found in the database
External Dependencies and Side Effects:
Accesses records in the degrees_of_freedom table in the database.
Example:
Please seedb_get_dof_id (p. 1146) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
222
Function Descriptions

db_get_dof_name ( dof_id, dof_name )

Description:
Get the degree of freedom name from its degree of freedom id.
Input:
INTEGER dof_id The degree of freedom id.
Output:
INTEGER dof_name The degree of freedom name.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000140 The DOF ID was not found in the database
External Dependencies and Side Effects:
Accesses records in the degrees_of_freedom table in the database.
Example:
Please see db_get_dof_name (p. 1146) in the MSC.Acumen, Volume 2: Code Examples.

db_get_mpc_type_id ( mpc_type_name, mpc_type_id )

Description:
Get the MPC type id from its MPC type name.
Input:
STRING mpc_type_name[] The MPC type name.
Output:
INTEGER mpc_type_id The MPC type id.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000152 The MPC type ID was not found in the database.
External Dependencies and Side Effects:
Accesses records in the mpc_type table in the database.
Example:
Please see db_get_mpc_type_id (p. 1164) in the MSC.Acumen, Volume 2: Code Examples.

db_get_mpc_type_name ( mpc_type_id, mpc_type_name )

Description:
Get the MPC type name from its MPC type id.
Input:
INTEGER mpc_type_id The MPC type id.

Main Index
CHAPTER 8 223
Finite Element Model

Output:
STRING mpc_type_name[] The MPC type id.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000152 The MPC type ID was not found in the database.
External Dependencies and Side Effects:
Accesses records in the mpc_type table in the database.
Example:
Please see db_get_mpc_type_name (p. 1165) in the MSC.Acumen, Volume 2: Code Examples.

db_get_valid_mpc_ids_in_group ( gid, nmpc, numval, mpcid )

Description:
Returns a list of ids for all valid MPCs in a group. A MPC is valid if it’s type and associated
degrees of freedom are valid for the current analysis code and analysis type preferences.
Input:
INTEGER gid The group id.
INTEGER nmpc The number of valid MPCs to be returned.
Output:
INTEGER numval The actual number of valid MPCs.
INTEGER mpcid() The MPC ids.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Error Conditions:
13000008 Group not found.
13000156 There are more than NMPC valid MPCs in the database.
External Dependencies and Side Effects:
Accesses records in the mpc, valid_mpc_type, control_info and analysis_code tables in the
database.
Example:
Please see db_get_valid_mpc_ids_in_group (p. 1175) in the MSC.Acumen, Volume 2: Code
Examples.

fem_get_mpc_assoc_groups ( nmpc, idmpcs, ngroups, assoc_group_ids )

Description:
Get a list of all the groups associated with the MPCs in the FEM_LIST.
Input:
INTEGER nmpc Number of MPCs.
INTEGER idmpcs List of MPCs.
Output:
INTEGER ngroups() Number of unique groups associated with MPCs.
Main Index
224
Function Descriptions

INTEGER assoc_group_ids Pointer to VIRTUAL integer array containing list of


associated group IDs.
INTEGER <Return Value> 0 Function was successful.
-1 Abort.
-2 No MPCs in list.
-3 No associated groups.
Example:
Please see fem_get_mpc_assoc_groups (p. 1184) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 8 225
Finite Element Model

8.3 Nodes

db_get_nodal_association ( nnode, nid, gid, gtype )

Description:
This function will retrieve the geometry type and ID that is associated with each node that is
specified.
Input:
INTEGER nnode The number of node IDs being supplied.
INTEGER nid() The array of nodes IDs to be looked up.
Output:
INTEGER gid() The array of geometry IDs (one for each node ID).
INTEGER gtype() The array of geometry types (one for each node ID).
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Example:
Please see db_get_nodal_association (p. 1169) in the MSC.Acumen, Volume 2: Code Examples.

db_get_node ( id, xyz )

Description:
Given a node ID, this function will look up the specified node and return the coordinates of that
node to the caller.
Input:
INTEGER id The node ID to be looked up.
Output:
REAL xyz(3) An array of 3 floating point values which are the
coordinates of the specified node.
INTEGER <Return Value> Integer indicating the success or failure of the routine.
Error Conditions:
SUCCESS This function completed successfully.
13000020 Node not found.
Example:
Please see db_get_node (p. 1170) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
226
Function Descriptions

db_get_nodes_by_lbc ( lbc_id, max_node, nnode, nid )

Description:
Gets all nodes associated with an specified lbc.
Input:
INTEGER lbc_id Id of the lbc to which the requested nodes are associated.
INTEGER max_node Maximum number of node ids for which storage has been
allocated by the calling routine.
Output:
INTEGER nnode Number of nodes found associated to the specified lbc.
INTEGER nid() Ids of the nodes associated to the specified lbc.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000048 Maximum node count exceeded.
External Dependencies and Side Effects:
None.
Example:
Please see db_get_nodes_by_lbc (p. 1170) in the MSC.Acumen, Volume 2: Code Examples.

db_get_nodes_for_geometry ( geo_type, geo_id, parent_type, parent_id, nnode, nids,


ncoord )

Description:
This function will retrieve information about all of the nodes associated with a given piece of
geometry.
Input:
INTEGER geo_type The type of geometry in question.
INTEGER geo_id The id of the geometry in question.
INTEGER parent_type The type of highest order geometry that the “geo-type” is
part of.
INTEGER parent_id The id of the highest order geometry that the “geo-type” is
part of.
Output:
INTEGER nnode The number of nodes found.
INTEGER nids() The IDs of all of the nodes found.
REAL ncoord() The model space coordinates of each node (x, y, z).
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
SUCCESS This function completed successfully.
Example:
Please see db_get_nodes_for_geometry (p. 1171) in the MSC.Acumen, Volume 2: Code
Examples.
Main Index
CHAPTER 8 227
Finite Element Model

db_get_next_node_id ( id )

Description:
This function will return the next available node ID to the caller. This can be used to create
another node.
Input:
None.
Output:
INTEGER id The next available node ID.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
SUCCESS This function completed successfully.
Example:
Please see db_get_next_node_id (p. 1167) in the MSC.Acumen, Volume 2: Code Examples.

db_get_min_node_id ( id )

Description:
This function will find the smallest node ID currently in use.
Input:
None.
Output:
INTEGER id The smallest node ID currently in use.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
SUCCESS This function completed successfully.
Example:
Please see db_get_min_node_id (p. 1163) in the MSC.Acumen, Volume 2: Code Examples.

db_get_max_node_id ( id )

Description:
This function will find the largest node ID currently in use.
Input:
None.
Output:
INTEGER id The largest node ID currently in use.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.
Main Index
228
Function Descriptions

Example:
See example for db_get_min_node_id (p. 227). See also db_get_max_node_id (p. 1161) in the
MSC.Acumen, Volume 2: Code Examples.

fem_get_node_assoc_groups ( nnode, idnodes, ngroups, ids )

Description:
Get a list of all the groups associated with the nodes in the FEM_LIST.
Input:
INTEGER nnode Number of nodes.
INTEGER idnodes() List of nodes.
Output:
INTEGER ngroups Number of unique groups associated with nodes.
INTEGER ids()symbol Pointer to VIRTUAL integer array containing list of
associated group IDs.
INTEGER <Return Value> 0 Function was successful.
-1 Abort
-2 No NODEs in list
-3 No associated groups
Error Conditions:
2001070 Unable to acquire %I% words of virtual memory.
4 Interrupted system call.
Example:
Please see fem_get_node_assoc_groups (p. 1187) in the MSC.Acumen, Volume 2: Code
Examples.

fem_get_node_ids ( entity_lst, nnode, idnode, notfound, idnoexist )

Description:
This function will sort a list of node id values, returning a list of existing nodes and a list of
nodes that do not exist.
Input:
STRING entity_list[] This value specifies a list of nodes.
Output:
INTEGER nnode This value returns the number of node id values in the
return value idnode.
INTEGER idnode(VIRTUAL) This value returns an array of node id values that refer
to nodes that do exist.
INTEGER notfound This value returns the number of node id values in the
return value idnoexist.
INTEGER idnoexist(VIRTUAL) This value returns an array of node id values that refer
to nodes that do not exist.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Main Index
CHAPTER 8 229
Finite Element Model

Error Conditions:
-1 Abort.
-2 No existing nodes in list
4 Interrupted system call.
2001070 Unable to acquire %I% words of virtual memory.
16000102 Database error during list processing: Node not found
Example:
See example for fem_get_node_assoc_groups (p. 228). See also fem_get_node_ids
(p. 1188) in the MSC.Acumen, Volume 2: Code Examples.

db_verify_nodes_exist ( nnode, nid, exist )

Description:
This function verifies that a set of node id values exist in the database.
Input:
INTEGER nnode This value specifies the number of node values listed in
the input value nid.
INTEGER nid(nnode) This value specifies the node ids to be checked.
Output:
INTEGER exist(nnode) This value specifies an array of integers used to return a
value of 0 if the id value at an offset into the input value
nid exists and a non-zero value if the id does not exist.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
13000020 Node not found.
Example:
Please see db_verify_nodes_exist (p. 1180) in the MSC.Acumen, Volume 2: Code Examples.

db_count_unref_nodes ( nbr_unref_node )

Description:
This function will count all of the nodes in the database which are not referenced by any of the
elements.
Input:
None.
Output:
INTEGER nbr_unref_node The number of unreferenced nodes in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the
reason.

Main Index
230
Function Descriptions

Error Conditions:
SUCCESS This function completed successfully.
13000020 Node not found.
Example:
Please see db_count_unref_nodes (p. 1140) in the MSC.Acumen, Volume 2: Code Examples.

db_get_unreferenced_node_ids ( nnode, nunref, nid )

Description:
This function will return the IDs and the count of all of the nodes in the database that are not
referenced by any elements or mpcs. If the specified count is less than the number of nodes in
the database, output will stop when the requested count has been reached. The order of the IDs
returned is not determinate.
Input:
INTEGER nnode The maximum number of nodes that can be returned.
Output:
INTEGER nunref The number of unreferenced nodes found.
INTEGER nid() The array of IDs of the unreferenced nodes.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
SUCCESS This function completed successfully.
13000048 Maximum node count exceeded.
Example:
Please see db_get_unreferenced_node_ids (p. 1175) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 8 231
Finite Element Model

8.4 Mesh

fem_create_mesh_sol_3 (<mesher_pick>,<flag>,<solid_list>,<num_val>,<g_leng>,
<elem_topo>,<node_list>,<elem_list>,<a_coord_frame>,
<r_coord_frame>,<num_nodes>,<num_elems>,
<nodes_created>, < elems_created> )

Description:
This function creates a finite element mesh on solids and returns the FEM data for the solid. It
returns an integer status of zero on successful completion.
Input:
STRING mesher_pick [ ] Mesher to be used: "IsoMesh" or "Tetmesh".
INTEGER flag Integer to specify use of preview. Used only with
“Tetmesh”.
STRING solid_list[ ] List of solids to be meshed.
INTEGER num_val Number of float values.
REAL g_leng Global element edge length.
STRING elem_topo[ ] Element topology.
STRING node_list[ ] List of output node ids.
STRING elem_list[ ] List of output element ids.
STRING a_coord_frame[ ] Analysis coordinate frame id.
STRING r_coord_frame[ ] Reference coordinate frame id.
Output:
INTEGER num_nodes Number of nodes created.
INTEGER num_elems Number of elements created.
STRING nodes_created[ ] Ids of nodes created.
STRING elems_created[ ] Ids of elements created.
INTEGER <Return Value> 0 for success, 1 for error.
Error Conditions:
None.
Example:
Please see fem_create_mesh_sol_3 (p. 1181) in the MSC.Acumen, Volume 2: Code Examples.

fem_seed_display_dir_arrows ( arrow_segment )

Description:
Display direction arrows on all visible curves.
Input:
INTEGER arrow_segment Graphics manager segment id for arrows.
Output:
INTEGER <Return Value> Integer indicating the success or failure of the routine.

Main Index
232
Function Descriptions

Error Conditions:
2001060 List overflow in %A%. Call customer support.
4 Interrupted system call.
Example:
Please see fem_seed_display_dir_arrows (p. 1189) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_mesh_params ( wmesh, mshcyc, relaxm, tolmsh, dgmesh, itrngl )

Description:
Gets the definition of an edge mesh from the database.
Input:
None.
Output:
REAL wmesh The unique internal line wmesh identifying the mesh to be
retrieved from the database.
INTEGER mshcyc The number of elements on the edge.
REAL relaxm The mesh relaxm of the edge.
REAL tolmsh The tolmsh of the edge.
INTEGER dgmesh The number of meshes on the edge.
INTEGER itrngl True if the edge has been itrngled.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Accesses one record in the “line” table in the database.
Example:
Please see db_get_mesh_params (p. 1162) in the MSC.Acumen, Volume 2: Code Examples.

move_mesh ( <surface_id_2 >, <surface_id_1>, <user_tolerance >)

Description:
The function moves the finite element entities – vertex nodes, edge nodes and the face nodes
with the elements from one surface to another. The size of the two surfaces should be equal and
the user tolerance should be at least equal to the normal distance between the two surfaces. It
returns an integer status of 0 on success and 1 on failure.
Input:
INTEGER surface_id_2 The id of the surface to which the mesh is to be moved.
INTEGER surface_id_1 The id of the surface from which the mesh is to be moved.
REAL user_tolerance The value of the user tolerance specified by the user.
Output:
INTEGER <Return Value> 0 for success and 1 for failure.

Main Index
CHAPTER 8 233
Finite Element Model

Error Conditions:
None.
Example:
Please see move_mesh (p. 1205) in the MSC.Acumen, Volume 2: Code Examples.

move_mesh_1 ( <surface_name_ 2 >, <surface_name _1>, <user_tolerance >)

Description:
The function moves the finite element entities – vertex nodes, edge nodes and the face nodes
with the elements from one surface to another. The size of the two surfaces should be equal and
the user tolerance should be at least equal to the normal distance between the two surfaces. It
returns an integer status of 0 on success and 1 on failure.
Input:
STRING surface_name_2[] The name of the surface to which the mesh is to be moved.
STRING surface_name_1[] The name of the surface from which the mesh is to be
moved.
REAL user_tolerance The value of the user tolerance specified by the user.
Output:
INTEGER <Return Value> 0 for success and 1 for failure.
Error Conditions:
None.
Example:
Please see move_mesh_1 (p. 1207) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
234
Function Descriptions

8.5 Element/Node Relations

db_count_elems_using_node ( nnode, nid, nelem, fflag )

Description:
This function will count the number of elements associated with the specified array of nodes in
the memory database.
Input:
INTEGER nnode The number of node ids in the node id array.
INTEGER nid() The array of node IDs to be looked for.
Output:
INTEGER nelem() The number of elements associated with this node.
INTEGER fflag A flag indicating if any nodes were not found.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000020 Node not found.
SUCCESS if the node exists and is associated with some elements.
Example:
Please see db_count_elems_using_node (p. 1136) in the MSC.Acumen, Volume 2: Code
Examples.

db_count_mpcs_using_node ( nnode, nid, nmpc, fflag )

Description:
This function will count the number of MPCs associated with a group of nodes.
Input:
INTEGER nnode This value specifies the number of node id values listed in the
input value nid.
INTEGER nid(nnode) This value specifies the id values of the nodes for which
information is being requested.
Output:
INTEGER nmpc(nnode) This value returns the number of MPCs using each node.
INTEGER fflag This value returns a non zero value if one or more of the
nodes listed in the input value nid are not found.
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an
error.
Error Conditions:
13000020 Node not found.
External Dependencies and Side Effects:
Accesses records in the mpc_term_node table in the database.
Example:
Please see db_count_mpcs_using_node (p. 1137) in the MSC.Acumen, Volume 2: Code
Examples.
Main Index
CHAPTER 8 235
Finite Element Model

db_count_nodes_in_mpc ( nmpc, mpcid, nnode, fflag )

Description:
Returns the total number of nodes in a specified MPC.
Input:
INTEGER nmpc The number of MPCs for which the information is being
requested.
INTEGER mpcid() The ids of the MPCs for which the information is being
requested.
Output:
INTEGER nnode() The number of nodes in each MPC.
INTEGER fflag An error flag indicating that one or more of the MPCs was
not found.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000142 The MPC was not found in the database.
External Dependencies and Side Effects:
Accesses records in the mpc_term_node table in the database.
Example:
Please see db_count_nodes_in_mpc (p. 1139) in the MSC.Acumen, Volume 2: Code Examples.

db_get_elems_using_nodes ( nnode, nid, mxelem, nelem, eid )

Description:
This function will retrieve the list of elements associated with the specified array of nodes in the
memory database.
Input:
INTEGER nnode The number of node IDs in the node ID array.
INTEGER nid() The array of node IDs to be looked for.
INTEGER mxelem The maximum number of elements allowed per node.
Output:
INTEGER nelem() The number of elements associated with this node.
INTEGER eid() The IDs of all elements referencing this node.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000020 Node not found.
SUCCESS If the node exists and is associated with some elements.
Example:
See example for db_count_elems_using_node (p. 234). See also
db_get_elems_using_nodes (p. 1157) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
236
Function Descriptions

db_get_elem_nodes ( eid, numnode, nid )

Description:
This function will retrieve all of the node IDs for a specified element. The nodes will be
returned in node position order.
Input:
INTEGER eid The element ID to be looked up.
Output:
INTEGER numnode The number of nodes associated with this element.
INTEGER nid() The array of node IDs associated with this element.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000020 Node not found.
SUCCESS If some nodes exist for this element.
Example:
Please see db_get_elem_nodes (p. 1150) in the MSC.Acumen, Volume 2: Code Examples.

db_get_nodes_in_mpc ( nmpc, mpcid, mxnode, nnode, nid )

Description:
Returns a list of all nodes which refer to the specified MPC.
Input:
INTEGER nmpc The number of MPCs ids for which the information is being
requested.
INTEGER mpcid() The ids of the MPCs for which the information is being
requested.
INTEGER mxnode The maximum number of nodes which may be returned per
MPC.
Output:
INTEGER nnode() The number of nodes using each MPC.
INTEGER nid() The ids of the nodes for each MPC.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000142 The MPC was not found in the database.
13000150 The list of nodes for one or more of the MPCs is longer than MAXNODE.
External Dependencies and Side Effects:
Accesses records in the mpc_term_node table in the database.
Example:
See example for db_count_nodes_in_mpc (p. 235). See also db_get_nodes_in_mpc (p. 1172)
in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 8 237
Finite Element Model

list_get_node_ass_el_edge (elem_edge_list, node_list)

Description:
This function gets the nodes associated to the specified element edges.
Input:
STRING elem_edge_list[] List of element edges.
Output:
STRING node_list[VIRTUAL] List of nodes.
INTEGER <Return Value> 0 for success.
Error Condition:
None
Example:
Please see list_get_node_ass_el_edge (p. 1194) in the MSC.Acumen, Volume 2: Code Examples.

list_get_node_ass_el_face (elem_face_list, node_list)

Description:
This function gets the nodes associated to the specified element faces.
Input:
STRING elem_face_list[] List of element faces.
Output:
STRING node_list[VIRTUAL] List of nodes.
INTEGER <Return Value> 0 for success.
Error Condition:
None
Example:
Please see list_get_node_ass_el_face (p. 1195) in the MSC.Acumen, Volume 2: Code Examples.

list_get_node_ass_elem (elem_list, node_list)

Description:
This function gets the nodes associated to the specified element.
Input:
STRING elem_list[] List of elements.
Output:
STRING node_list[VIRTUAL] List of nodes.
INTEGER <Return Value> 0 for success.
Error Condition:
None
Example:
Please see list_get_node_ass_elem (p. 1196) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
238
Function Descriptions

list_get_node_ass_geo (ent_list, node_list)

Description:
This function gets the nodes associated to the specified geometry entities.
Input:
STRING ent_list[] List of geometry entities.
Output:
STRING node_list[VIRTUAL] List of nodes.
INTEGER <Return Value> 0 for success.
Error Condition:
None
Example:
Please see list_get_node_ass_geo (p. 1197) in the MSC.Acumen, Volume 2: Code Examples.

list_get_node_ass_group (num, group_list, node_list)

Description:
This function gets the nodes associated to the specified groups.
Input:
INTEGER num Number of groups.
STRING ARRAY group_list[]() Array of group names.
Output:
STRING node_list[VIRTUAL] List of nodes.
INTEGER <Return Value> 0 for success.
Error Condition:
None
Example:
Please see list_get_node_ass_group (p. 1199) in the MSC.Acumen, Volume 2: Code Examples.

list_get_node_ass_mpc (mpc_list, node_list)

Description:
This function gets the nodes associated to the specified mpcs.
Input:
STRING mpc_list[] List of mpcs.
Output:
STRING node_list[VIRTUAL] List of nodes.
INTEGER <Return Value> 0 for success.
Error Condition:
None
Example:
Please see list_get_node_ass_mpc (p. 1200) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 8 239
Finite Element Model

list_get_node_att_fringe (val, act, tol, group, node_list)

Description:
This function gets the nodes associated with a specified fringe range.
Input:
REAL val(2) Upper & lower fringe value.
STRING act[80] Method name.
REAL tol Tolerance of xyz or rpt if applicable.
STRING group[32] Group name which has the fringe table.
Output:
STRING node_list[VIRTUAL] List of nodes.
INTEGER <Return Value> 0 for success.
Error Condition:
None
Example:
Please see list_get_node_att_fringe (p. 1202) in the MSC.Acumen, Volume 2: Code Examples.

list_get_node_att_value (val_xyz, val_log, act, tol, coord, group, node_list)

Description:
This function gets the nodes associated with a specified coordinate value.
Input:
REAL ARRAY val_xyz(3) Value of xyz or rpt coordinate.
LOGICAL ARRAY val_log(3) Logical value specifying active coords.
STRING ARRAY act[80](3) Method name.
REAL ARRAY tol(3) Tolerance of xyz or rpt if applicable.
STRING coord[32] Coordinate frame
LOGICAL group Logical value for group.
Output:
STRING node_list[VIRTUAL] List of nodes.
INTEGER <Return Value> 0 for success.
Error Condition:
None
Example:
Please see list_get_node_att_value (p. 1204) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
240
Function Descriptions

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Load Cases
9
■ General

Main Index
242
Function Descriptions

9.1 General

db_activate_load_case (name)

Description:
Activates the specified load case in the model.
Input:
STRING name[80] Name of the load case to be activated.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason
Error Conditions:
13000002 Unrecoverable database error.
13000052 Load Case Not Found.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Updates one record in the “load case” table in the database.
Example:
Please see db_activate_load_case (p. 1210) in the MSC.Acumen, Volume 2: Code Examples.

db_delete_load_case

Description:
Deletes a load case entry from the database
Input:
STRING name[80] Name of the load case to be deleted.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason
Error Conditions:
13000002 Unrecoverable database error.
13000052 Load Case Not Found.
13000076 Load case active
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Deletes one record in the “load case” table in the database.
Example:
Please see db_delete_load_case (p. 1211) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 9 243
Load Cases

db_find_load_case_id ( jbname, lc_seqno, lc_id )

Description:
Gets all load case ids from the database in one structure.
Input:
STRING jbname[] The jobname used for the desired run.
INTEGER lc_seqno The load case sequence number for the desired load case.
Output:
INTEGER lc_id The id of the desired load case.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
13000052 Load Case Not Found.
External Dependencies and Side Effects:
Accesses the “load_case” table in the database and retrieves an id of a specified jobname/load
case sequence number.
Example:
Please see db_find_load_case_id (p. 1212) in the MSC.Acumen, Volume 2: Code Examples.

db_count_load_cases ( load_case_count )

Description:
This function returns the number of load cases defined in the database.
Input:
none
Output:
INTEGER load_case_count This value returns the number of load cases defined in the
database.
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an
error.
Example:
None.

db_get_all_load_case_names ( )

Description:
Gets all load cases from the database.
Input:
None

Main Index
244
Function Descriptions

Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason
Example:
None.

db_get_all_load_cases ( )

Description:
This function will set a cursor to the start of a list of load cases.
Input:
None
Output:
None
Remarks:
This function must be called before the db_get_next_load_case() function can be called.
Example:
None.

db_get_next_load_case ( name, id, type, description, num_lbc, lbc, dyn_load, map,


priority )

Description:
This function will get the next load case from the database.
Input:
None
Output:
STRING name[80] This value returns the name of the load case retrieved.
INTEGER id This value returns the load case id.
INTEGER type This value returns the load case type.
STRING description[256] This value returns the description of the load case.
INTEGER num_lbc This value returns the number of load and boundary
conditions associated with the load case.
INTEGER lbc[num_lbc] This value returns the ids of the loads and boundary
conditions associated with this load case.
INTEGER dyn_load This value returns the name of the dynamic load case
used as a basis for this load case. This value is valid only
if the load case is a static load case created from a
dynamic load case.
REAL map This value returns a map variable.
INTEGER priority This value returns the priority assigned to the load case.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Main Index
CHAPTER 9 245
Load Cases

Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
13000085 Cursor not open.
13000117 The query specified has completed.
External Dependencies and Side Effects:
Accesses all records in the “load case” table in the database.
Remarks:
The PCL function db_get_all_load_cases (p. 244) must be called at least once to establish the
list of posted coordinate frame id values and to set the cursor to point to the start of the list.
Calling the db_get_next_posted_coord (p. 194) function in a loop will then allow the list
entries to be retrieved.
Example:
None.

db_get_lc_id_given_job_seq ( ac_id, jobname, lcseq, lcid )

Description:
Gets all load case ids from the database in one structure.
Input:
INTEGER ac_id Analysis code id for the requested jobname.
STRING jobname[] The jobname used for the desired run.
INTEGER lcseq The load case sequence number for the desired load case.
Output:
INTEGER lcid The id of the desired load case.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
13000052 Load Case Not Found
External Dependencies and Side Effects:
Accesses the “load_case” table in the database and retrieves an id of a specified jobname/load
case sequence number.
Example:
Please see db_get_lc_id_given_job_seq (p. 1213) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
246
Function Descriptions

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Element Properties
10
■ General

Main Index
248
Function Descriptions

10.1 General

bl_create_std_beam_section (<shape>,<name>,<ndim>,<data_types>,<rvalues>,
<field_ids>,<id>)
Description:
This function will create a standard beam section.
Input:
STRING shape [] Standard shape of the beam section.
STRING name [] Name for the beam section created.
INTEGER ndim Number of dimension required for corresponding beam
section shape.
INTEGER data_types() Type of data for each dimension.
REAL rvalues() Dimension values for beam section
INTEGER field_ids() Field ids for beam section.
Output:
INTEGER id ID of beam section
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
NONE
Example:
Please see bl_create_std_beam_section (p. 1218) in the MSC.Acumen, Volume 2: Code
Examples.

bl_get_std_beam_section_data (<id>,<ndim>,<data_types>,<rvalues>,<field_ids>)

Description:
This function will get standard beam section data.
Input:
INTEGER id [] Id of the beam section for which data is required.
INTEGER ndim Number of dimension required for beam section shape.
Output:
INTEGER data_types() Type of data for each dimension.
REAL rvalues() Dimension values for beam section.
INTEGER field_ids() Field ids for beam section.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
NONE
Example:
Please see bl_get_std_beam_section_data (p. 1219) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 10 249
Element Properties

bl_modify_std_beam_section (<new_shape>,<old_name>,<new_name>,<ndim>,<da
ta_types>,<rvalues>,<field_ids>,<id>)
Description:
This function will modify the existing standard beam section.
Input:
STRING new_shape [] Standard shape of the beam section.
STRING old_name [] Name of the existing beam section .
STRING new_name[] Name for the modified beam section.
INTEGER ndim Number of dimension required for modified beam section
shape.
INTEGER data_types() Type of data for each dimension.
REAL rvalues() Dimension values for modified beam section.
INTEGER field_ids() Field ids for modified beam section.
Output:
INTEGER id ID of the modified beam section.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
1 Invalid shape name
Example:
Please see bl_modify_std_beam_section (p. 1221) in the MSC.Acumen, Volume 2: Code
Examples.

blcomputeprincaxespoints (<alpha>,<npoints>,<points>,<centroid>,<princ_axis1>,
<princ_axis2>)
Description:
This function calculates principal axes vectors for the beam section from the principal angle
alpha. It also scales the axes based on the beam section points.
Input:
REAL alpha Principal angle for the beam section.
INTEGER npoints Number of points for beam section shape.
REAL points() Coordinates for each point
REAL centroid(2) Coordinates for centroid of beam section.
Output:
REAL princ_axis1(2) First principal axis
REAL princ_axis2(2) Second principal axis.
INTEGER <Return Value> Returns 0 for success.
Error Conditions:
NONE
Example:
Please see blcomputeprincaxespoints (p. 1223) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
250
Function Descriptions

blgetalpha (<entype>,<prop>,<alpha>)

Description:
This function calculates principal angle for the beam section from the given properties of a
beam section.
Input:
INTEGER entype Type of beam secion (1=Basic, 2=Advanced)
REAL prop() Properties of beam section.
Output:
REAL alpha Principal angle for the beam section.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
1 Invalid entype.
2 Extremely small Izz or Iyy in property definition.
Example:
Please see blgetalpha (p. 1224) in the MSC.Acumen, Volume 2: Code Examples.

blgetbuttonicon (<shape>,<cdo>)

Description:
This function gets the file system location of the button icon bitmap for a shape.
Input:
STRING shape Shape of the beam section.
Output:
STRING cdo[] File system location of the button icon bitmap for a shape.
INTEGER <Return Value> Returns 0 for success,otherwise returns the error code.
Error Conditions:
1 Invalid shape name
Example:
Please see blgetbuttonicon (p. 1225) in the MSC.Acumen, Volume 2: Code Examples.

blgetcenters (<enttype>,<shape>,<dim>,<prop>,<centroid>,<shear>)

Description:
This function calculates the centroid and sheare centre of the beam section.
Input:
INTEGER enttype Type of beam secion (1=Basic, 2=Advanced)
STRING shape Shape of the beam section.
REAL dim() Dimensions for the beam section shape.
REAL prop() Properties of beam section.
Output:
REAL centroid() Centroid of the beam section.
REAL shear() Shear center of the beam section.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
1 Invalid area in property definition
Main Index
CHAPTER 10 251
Element Properties

Example:
Please see blgetcenters (p. 1226) in the MSC.Acumen, Volume 2: Code Examples.

blgetdimfieldid (<bsid>,<dim_loc>,<field_id>)

Description:
This function will get the field id at specified dimension location.
Input:
INTEGER bsid Beam section ID.
STRING dim_loc Dimension location.
Output:
INTEGER field_id Field id at specified dimension location.
INTEGER <Return Value> Returns 0 for success.
Error Conditions:
NONE
Example:
Please see blgetdimfieldid (p. 1227) in the MSC.Acumen, Volume 2: Code Examples.

blgetdimvalue (<bsid>,<dim_loc>,<value>)

Description:
This function will get the value at the specified dimension location.
Input:
INTEGER bsid Beam section ID.
STRING dim_loc Dimension location.
Output:
REAL value Value at specified dimension location.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
NONE
Example:
Please see blgetdimvalue (p. 1228) in the MSC.Acumen, Volume 2: Code Examples.

blgetlabelicon (<shape>,<cdo>)

Description:
This function gets the file system location of the label icon bitmap for a shape.
Input:
STRING shape Shape of the beam section.
Output:
STRING cdo[] File system location of the label icon bitmap for a shape.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
1 Invalid shape name.

Main Index
252
Function Descriptions

Example:
Please see blgetlabelicon (p. 1230) in the MSC.Acumen, Volume 2: Code Examples.

blgetlabels (<shape>,<cdo>)

Description:
This function gets the dimension labels for a given shape.
Input:
STRING shape[] Shape of the beam section.
Output:
STRING ARRAY cdo[]() String array of dimension labels for beam section shape.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
1 Invalid shape name.
Example:
Please see blgetlabels (p. 1231) in the MSC.Acumen, Volume 2: Code Examples.

blgetnumdimension (<shape>)

Description:
This function gets the number of dimensions required to define a given shape completely.
Input:
STRING shape[] Shape of the beam section.
Output:
INTEGER ndim No. of dimensions required for beam section shape.
<Return Value>
Error Conditions:
1 Invalid shape name.
Example:
Please see blgetnumdimension (p. 1231) in the MSC.Acumen, Volume 2: Code Examples.

blgetnumplotpoints (<shape>,<chord_tol>,<npoints>,<nloops>)

Description:
This function will get the number of total plot points and loops used to draw a given shape.
Input:
STRING shape[] Beam section shape.
REAL chord_tol Chordal tolerance for rod and tube.
Output:
INTEGER npoints Number of total plot points.
INTEGER nloops Number of loops.
INTEGER <Return Value> Returns 0 for success, othewise returns the error code.
Error Conditions:
1 Invalid shape name

Main Index
CHAPTER 10 253
Element Properties

Example:
Please see blgetnumplotpoints (p. 1232) in the MSC.Acumen, Volume 2: Code Examples.

blgetnumplotpointsbyid (<bsid>,<chord_tol>,<npoints>,<nloops>)

Description:
This function will get the number of total plot points and loops used to draw a shape of beam
section.
Input:
INTEGER bsid ID of beam section.
REAL chord_tol Chordal tolerance for rod and tube.
Output:
INTEGER npoints Number of total plot points.
INTEGER nloops Number of loops.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
1 Invalid shape name
Example:
Please see blgetnumplotpointsbyid (p. 1233) in the MSC.Acumen, Volume 2: Code Examples.

blgetnumtypeinfo (<nsect>,<ndimax>)

Description:
This function will get the number of section types available in MSC.Patran and the maximum
number of dimensions for any section.
Input:

Output:
INTEGER nsect Number of different section types.
INTEGER ndimax Maximum number of dimensions for any section.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
NONE
Example:
Please see blgetnumtypeinfo (p. 1235) in the MSC.Acumen, Volume 2: Code Examples.

blgetperim (<shape>,<dim>,<perim>)

Description:
This function calculates the exterior perimeter of a beam section.
Input:
STRING shape[] Beam section shape.
REAL ARRAY dim() Array of dimensions of the section.
Output:
REAL perim Perimeter of the beam section.
Main Index
254
Function Descriptions

INTEGER <Return Value> Returns 0 for success, otherwise returns the error
code.
Error Conditions:
1 Invalid shape name
Example;
Please see blgetperim (p. 1235) in the MSC.Acumen, Volume 2: Code Examples.

blgetplotpoints (<shape>,<dim>,<npoints>,<nloops>,<points>,<nploops>)

Description:
This function gets the coordinates of plot points and the number of plot points on each loop for
given section shape.
Input:
STRING shape[] Beam section shape.
REAL ARRAY dim() Array of dimensions of the section.
INTEGER npoints Number of total plot points.
INTEGER nloops Number of loops.
Output:
REAL ARRAY points() Coordinates of plot points for the section.
INTEGER ARRAY nploops() Array of number of plot points on each loop.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
1 Invalid shape name, npoints or nloops
Example:
Please see blgetplotpoints (p. 1236) in the MSC.Acumen, Volume 2: Code Examples.

blgetplotpointsbyid (<bsid>,<bmtype>,<enttype>,<entid>,<nparloc>,<nrmflg>,
<npoints>,<nloops>,<points>,<nploop>,<vec1s>,<vec2s>,<xyz>)
Description:
This function gets the coordinates of plot points and the number of plot points on each loop for
given beam section id, entity type, entity id and entity parametric location. This function calls
blgetplotpointsbyid2, and hardwires the displaymode argument in blgetplotpointsbyid2 to 1
(flag to process offsets).
Input:
INTEGER bsid Beam section id stored in db or region id for Abaqus beams.
INTEGER bmtype Beam type 1 = Bar , 2 = Beam, 3 for aero bodies. For Abaqus
beams:
1001 = Box section
1002 = Circular section
1003 = I section
1004 = L section
1005 = Pipe section
1006 = Rectangular section
1007 = Hex section
1008 = Trapazoidal section
1009 = Arbitrary section
Main Index
CHAPTER 10 255
Element Properties

INTEGER enttype Entity type, currently only type 124 is supported.


INTEGER entid Entity id
INTEGER nparloc Number of parametric locations.
REAL parloc(nparloc) One dimensional parametric location on entity.
INTEGER nrmflg If =1, normal is calculated.
INTEGER npoints Number of total plot points for one parametric location.
INTEGER nloop Number of loops for one parametric location.
Output:
REAL points(npoints*nparl Coordinates of plot points for the section. One set of points
oc,nparloc) per parametric location.
INTEGER nploops(nloop) Array of number of plot points on each loop for one
parametric location.
REAL vec1s(nparloc,3) Array of nparloc axis 1 orientation vectors.
REAL vec2s(nparloc,3) Array of nparloc axis 2 orientation vectors.
REAL xyz(nparloc*3) Array of evaluated xyz coordinates at the input parametric
locations.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
See the Status Message (Ch 11) for information on any error values returned by this function.
Example:
Please see blgetplotpointsbyid2 (p. 1240) in the MSC.Acumen, Volume 2: Code Examples.

blgetplotpointsbyid2 (<bsid>,<bmtype>,<enttype>,<entid>,<nparloc>,<nrmflg>,
<npoints>,<nloops>,<displaymode>,<points>,<nploop>,
<vec1s>,<vec2s>,<xyz>)
Description:
This function gets the coordinates of plot points and the number of plot points on each loop for
given beam section id, entity type, entity id and entity parametric location.
Input:
INTEGER bsid Beam section id stored in db or region id for Abaqus beams.
INTEGER bmtype Beam type 1 = Bar , 2 = Beam, 3 for aero bodies. For Abaqus
beams:
1001 = Box section
1002 = Circular section
1003 = I section
1004 = L section
1005 = Pipe section
1006 = Rectangular section
1007 = Hex section
1008 = Trapazoidal section
1009 = Arbitrary section
INTEGER enttype Entity type, currently only type 124 is supported.
INTEGER entid Entity id
INTEGER nparloc Number of parametric locations.
REAL parloc(nparloc) One dimensional parametric locations on entity.
INTEGER nrmflg If =1, calculates normals.
INTEGER npoints Number of total plot points for one parametric location.
Main Index
256
Function Descriptions

INTEGER nloops Number of loops for one parametric location


INTEGER displaymode If beam type = 1 or 2, this flag is whether to process offsets.
0 = do not process
1 = process
If beam type = 3 this flag is whether slender only,
interference only, both or none should display.
0 = None
1 = Slender
2 = Interference
3 = All
Output:
REAL points(npoints*nparl Coordinates of plot points for the section. One set of points
oc,nparloc) perparametric location.
INTEGER nploop(nloop) Array of number of plot points on each loop for one
parametric location.
REAL vec1s(nparloc,3) Array of nparloc axis 1 orientation vectors
REAL vec2s(nparloc,3) Array of nparloc axis 2 orientation vectors
REAL xyz(nparloc*3) Array of evaluated xyz coordinates at the input parametric
locations
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
See the Status Message (Ch 11) for information on any error values returned by this function.
Example:
Please see blgetplotpointsbyid2 (p. 255) in the MSC.Acumen, Volume 1: Function Descriptions.

blgetprop (<enttyp>,<shape>,<dim>,<ndim>,<prop>,<nprop>)

Description:
This function will get the all properties of beam section.
Input:
INTEGER enttyp Beam type (1 = Basic(Bar), 2 = Advanced(Beam))
STRING shape[] Beam section shape. See beam_section_create for valid
beam sections.
REAL dim(ndim) Array of dimensions of the section.
INTEGER ndim Number of dimensions.
Output:
REAL prop() Properties of the beam section.
INTEGER nprop Number of properties
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
See the Status Message(Ch 11) for information on any error values returned by this function.
Example:
Please see blgetprop (p. 1243) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 10 257
Element Properties

blgetproplabels (<enttyp>,<cdo>)

Description:
This function will get the propery labels for given beam entity type.
Input:
INTEGER enttyp Beam type (1 = Basic(Bar), 2 = Advanced(Beam))
Output:
STRING cdo[]() Array of property label strings.
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
1 Invalid Entity type.
Example:
Please see blgetproplabels (p. 1244) in the MSC.Acumen, Volume 2: Code Examples.

blgettypeinfo (<entype>,<shapes>,<ndims>,<nconsts>)

Description:
This function will get the beam shape name, number of dimensions for each beam shape and
the number of dimensional constraints for each beam shape available in the MSC.Patran library.
Input:
INTEGER entype Beam type(1=Basic(Bar), 2=Advanced(Beam))
Output:
STRING shapes[] Array of shape names
INTEGER ndims[] Array of the number of dimensions for each shape
INTEGER nconsts[] Array of the number of dimensional constraints
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
1 Invalid entype
Example:
Please see blgettypeinfo (p. 1245) in the MSC.Acumen, Volume 2: Code Examples.

blmodifybeamdimension (<bsid>,<dimid>,<value>,<fid>)

Description:
This function will modify the beam section dimension.
Input:
INTEGER bsid ID of beam section.
INTEGER dimid Dimension location.
REAL value New dimension value.
INTEGER fid Field id.
Output:
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
See the Status Message(Ch 11) for information on any error values returned by this function.

Main Index
258
Function Descriptions

Example:
Please see blmodifybeamdimension (p. 1246) in the MSC.Acumen, Volume 2: Code Examples.

db_create_selected_etype (atid, acid, geopcd, copcd, fopcd, lopcd, etopid, dofsetid,


mlcd, mdcd, etypid)

Description:
Create a selected element type entry in the database.
Input:
INTEGER atid The ID of the analysis type associated to the selected element
type.
INTEGER acid The ID of the analysis code associated to the selected element
type.
INTEGER geopcd The ID of the geometric option code associated with the selected
element type.
INTEGER copcd The ID of the condense option code associated with the selected
element type.
INTEGER fopcd The ID of the formulation option code associated with the
selected element type.
INTEGER lopcd The ID of the laminate option code associated with the selected
element type.
INTEGER etopid The ID of the element topology associated with the selected
element type.
INTEGER dofsetid The ID of the degree of freedom associated with the selected
element type.
INTEGER mlcd The ID of the material linearity code associated with the selected
element type.
INTEGER mdcd The ID of the material directionality code associated with the
selected element type.
INTEGER etypid The ID of the element type associated with the selected element
type.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the routine
failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Creates one record in the “selected_element_type” relation in the database. Verifies all input
fields in their respective tables to verify their existence in the database before creating the entry.
Example:
Please see db_create_selected_etype (p. 1269) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 10 259
Element Properties

db_count_elem_type (acid, atid, etcnt)

Description:
This function will return a count of the number of distinct element types for each element
dimensionality for a specified analysis code and type.
Input:
INTEGER acid This value specifies the analysis code id.
INTEGER atid This value specifies the analysis type id.
Output:
INTEGER etcnt(4) This value returns the count of element types, one for
each element dimensionality.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Example:
Please see db_count_elem_type (p. 1261) in the MSC.Acumen, Volume 2: Code Examples.

db_count_etop_for_a_code ( acid, atid, count )

Description:
This function will return a count of element types for all element topologies for a specific
analysis code and type.
Input:
INTEGER acid This value specifies the analysis code id.
INTEGER atid This value specifies the analysis type id.
Output:
INTEGER count This value returns the count of element types for all element
topologies.
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an error.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
Example:
Please see db_count_etop_for_a_code (p. 1263) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_dof_set_names ( )

Description:
Sets db_get_next_dof_set_names to start at the beginning of a list of dof_set code names and ids
from the database.
Input:
None.

Main Index
260
Function Descriptions

Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000007 The query specified has completed.
13000117 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “dof_set” table in the database.
Example:
See example for db_get_all_cond_opt_code_names (p. 327). See also
db_get_all_dof_set_names (p. 1277) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_dof_set_names ( name, id )

Description:
Gets the next dof_set code names and id from the database.
Input:
None.
Output:
STRING name[31] The name retrieved from the database.
INTEGER id Id corresponding to the name retrieved.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000007 The query specified has completed.
13000117 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “dof_set” table in the database.
Example:
See example for db_get_all_cond_opt_code_names (p. 327). See also
db_get_next_dof_set_names (p. 1290) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_form_opt_code_names ( )

Description:
Gets the next dof_set code names and id from the database.
Input:
None.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.

Main Index
CHAPTER 10 261
Element Properties

Error Conditions:
13000002 Unrecoverable database error.
13000007 The query specified has completed.
13000117 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “formulation_option” table in the database.
Example:
See example for db_get_all_cond_opt_code_names (p. 327). See also
db_get_all_form_opt_code_names (p. 1279) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_form_opt_code_names ( name, id )

Description:
Gets the next formulation option code name from the database.
Input:
None.
Output:
STRING name[31] The name retrieved from the database.
INTEGER id The ID retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000007 The query specified has completed.
13000117 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “formulation_option” table in the database.
Example:
See example for db_get_all_cond_opt_code_names (p. 327). See also
db_get_next_form_opt_code_names (p. 1292) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_geo_opt_code_names ( )

Description:
Sets the db_get_next_geo_opt_code_names to start at the beginning of a list of geometric
option code names.
Input:
None.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.

Main Index
262
Function Descriptions

Error Conditions:
13000002 Unrecoverable database error.
13000007 The query specified has completed.
13000117 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “geometric_option” table in the database.
Example:
See example for db_get_all_cond_opt_code_names (p. 327). See also
db_get_all_geo_opt_code_names (p. 1279) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_geo_opt_code_names ( name, id )

Description:
Gets the next formulation option code name from the database.
Input:
None.
Output:
STRING name[31] The name retrieved from the database.
INTEGER id The ID retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000007 The query specified has completed.
13000117 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “geometric_option” table in the database.
Example:
See example for db_get_all_cond_opt_code_names (p. 327). See also
db_get_next_geo_opt_code_names (p. 1292) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_lam_opt_code_names ( )

Description:
Set db_get_next_lam_opt_code_names to start at the beginning of a list of laminate_option code
names from the database.
Input:
None.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.

Main Index
CHAPTER 10 263
Element Properties

Error Conditions:
13000002 Unrecoverable database error.
13000007 The query specified has completed.
13000117 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “laminate_option” table in the database.
Example:
See example for db_get_all_cond_opt_code_names (p. 327). See also
db_get_all_lam_opt_code_names (p. 1280) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_lam_opt_code_names ( name, id )

Description:
Gets all laminate_option code names from the database, in get all, get next method.
Input:
None.
Output:
STRING name[31] The name retrieved from the database.
INTEGER id The ID retrieved from the database.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000007 The query specified has completed.
13000117 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “laminate_option” table in the database.
Example:
See example for db_get_all_cond_opt_code_names (p. 327). See also
db_get_next_lam_opt_code_names (p. 1293) in the MSC.Acumen, Volume 2: Code Examples.

db_get_region_for_geometry ( entity_type, entity_id, rid )

Description:
Returns the region id for the given entity type and entity id.
Input:
INTEGER entity_type The entity type.
INTEGER entity_id The entity ID.
Output:
INTEGER rid The region ID.
INTEGER <Return Value> Returns the success or failure of the routine.
External Dependencies and Side Effects:
This routine access the geometric_region_list table in the database.

Main Index
264
Function Descriptions

Example:
Please see db_get_region_for_geometry (p. 1296) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_region_ids_and_names ( count, rid, name )

Description:
Gets all region ids from the database.
Input:
INTEGER count The number of region IDs for which storage has been
allocated by the calling routine.
Output:
INTEGER rid(count) The region IDs.
STRING name[31](count) The region names.
INTEGER <Return Value> Returns the success or failure of the routine.
External Dependencies and Side Effects:
This routine accesses the phys_prop_region table in the database.
Example:
Please see db_get_region_ids_and_names (p. 1297) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_elements_in_region_exp ( count, rid, eid )

Description:
Gets all element ids for a specified region id from the database.
Input:
INTEGER count The number of region IDs for which storage has been
allocated by the calling routine.
INTEGER rid The region ID for which the list of element IDs is requested.
Output:
INTEGER eid() The element IDs for the region.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Accesses specified records in the “element_in__region” table.
Example:
Please see db_get_elements_in_region_exp (p. 1286) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
CHAPTER 10 265
Element Properties

db_get_etop_for_a_code ( acid, atid, count, etids )

Description:
Retrieves a set of element_topology_ids based on analysis code id and analysis type id.
Input:
INTEGER acid The analysis code ID.
INTEGER atid The analysis type ID.
INTEGER count The count of element types, one for each element
dimensionality.
Output:
INTEGER etids() The list of element type IDs retrieved.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Retrieves analysis_elements relationships.
Example:
See example for db_count_etop_for_a_code (p. 259). See also db_get_etop_for_a_code
(p. 1287) in the MSC.Acumen, Volume 2: Code Examples.

db_get_a_phys_prop_w_nord ( acid, ppid, defid, alias, rflag, atypes, dtype, nord,


aival, arval, acval )

Description:
Creates an allowable physical property entry in the database.
Input:
INTEGER acid The ID of the analysis code for which this physical property
is to be allowed.
INTEGER ppid The ID of the physical property to be allowed.
INTEGER defid The ID of the physical property member set defn allowed.
Output:
STRING alias[] The alias to be used for this physical property from this
analysis code.
INTEGER rflag Flag indicating whether or not this property is required.
INTEGER atypes(10) Allowable types for this physical property.
INTEGER dtype Default type for this physical prop.
INTEGER nord Neutral file order for this physical property from
phys_prop_set_mbr_defn.
STRING aival[] PCL function to be used to validate integer values.
STRING arval[] PCL function to be used to validate real values.
STRING acval[] PCL function to be used to validate character values.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.

Main Index
266
Function Descriptions

Error Conditions:
13000002 Unrecoverable database error.
13000004 Duplicate entry exists in table.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Creates one record in the “allowable_phys_prop” table in the database.
Example:
Please see db_get_a_phys_prop_w_nord (p. 1275) in the MSC.Acumen, Volume 2: Code
Examples.

db_create_phys_prop_set_defn ( id, name, num, ppids )

Description:
Creates a physical property set entry in the database.
Input:
INTEGER id The ID of the physical property set to be created.
STRING name[] The name of the physical property set to be created.
INTEGER num The number of physical properties to be associated with this set.
INTEGER ppids() The IDs of the physical properties to be associated with this set
defn.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the routine
failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000004 Duplicate entry exists in table.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Creates one record in the “phys_prop_set_defn” table in the database.
Example:
Please see db_create_phys_prop_set_defn (p. 1268) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_phys_prop_set_defn ( id, name, num, ppids )

Description:
Get physical property definition from the database.
Input:
INTEGER id The set ID for which the physical property IDs are requested.
Output:
STRING name[] The name of the physical property set.
INTEGER num The number of physical property values associated with this
set.

Main Index
CHAPTER 10 267
Element Properties

INTEGER ppids() The IDs of the physical property values associated with this
set.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Specified.
Example:
See example for db_get_allowable_phys_prop (p. 267). See also
db_get_phys_prop_set_defn (p. 1295) in the MSC.Acumen, Volume 2: Code Examples.

db_get_allowable_phys_prop ( acid, ppid, alias, rflag, atypes, dtype, nord, aival, arval,
acval )

Description:
Creates an allowable physical property entry in the database.
Input:
INTEGER acid The ID of the analysis code for which this physical property
is to be allowed.
INTEGER ppid The ID of the physical property to be allowed.
Output:
STRING alias[] The alias to be used for this physical property from this
analysis code.
INTEGER rflag Flag indicating whether or not this property is required.
INTEGER atypes(10) Allowable types for this physical property.
INTEGER dtype Default type for this physical prop.
INTEGER nord Neutral file order for this physical property.
STRING aival[] PCL function to be used to validate integer values.
STRING arval[] PCL function to be used to validate real values.
STRING acval[] PCL function to be used to validate character values.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000004 Duplicate entry exists in table.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Creates one record in the “allowable_phys_prop” table in the database.
Example:
Please see db_get_allowable_phys_prop (p. 1282) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
268
Function Descriptions

db_get_selected_prop_set ( atid, acid, geopcd, copcd, fopcd, lopcd, etopid, dofsetid,


physprop )

Description:
Gets a field in the database.
Input:
INTEGER atid The ID of the analysis type associated to the selected
property set.
INTEGER acid The ID of the analysis code associated to the selected
property set.
INTEGER geopcd The ID of the geometric option code associated with the
selected property set.
INTEGER copcd The ID of the condense option code associated with the
selected property set.
INTEGER fopcd The ID of the formulation option code associated with the
selected property set.
INTEGER lopcd The ID of the laminate option code associated with the
selected property set.
INTEGER etopid The ID of the element topology associated with the selected
property set.
INTEGER dofsetid The ID of the physical property to be allowed.
Output:
STRING physprop The ID of the associated physical property set.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Gets a record in the “selected_property_set” table.
Example:
See example for db_bulk_get_selected_etops_mat (p. 279). See also
db_get_selected_prop_set (p. 1298) in the MSC.Acumen, Volume 2: Code Examples.

db_delete_phys_prop_region ( prop_reg_id )

Description:
This function will delete a physical property region from the database.
Input:
INTEGER prop_reg_id This value specifies the physical property region id.
Output:
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an
error.

Main Index
CHAPTER 10 269
Element Properties

Error Conditions:
13000002 Unrecoverable database error.
13000125 The property entered does not exist.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Deletes one record in the “phys_prop_region”, and any record associated to the specified
physical property in the “element_in_region” or “geometric_region_list” relations in the
database.
Example:
Please see db_delete_phys_prop_region (p. 1274) in the MSC.Acumen, Volume 2: Code
Examples.

db_associate_geo_to_region ( gid, gtype, gsid, rid )

Description:
Associates a specified region to a geometric entity in the database.
Input:
INTEGER gid The internal ID for the geometric entity to associate with the
region.
INTEGER gtype The type of geometric entity to which the region is being
associated.
INTEGER gsid The internal sub_id for the geometric entity to associate with
the region.
INTEGER rid The internal ID of the region being associated to the
geometric entity.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000004 Duplicate entry exists in table.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Creates one record associating a region to a geometric entity in the database for the region id
passed to the routine.
Example:
Please see db_associate_geo_to_region (p. 1247) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
270
Function Descriptions

db_count_geo_in_region ( rid, count )

Description:
Retrieves the count of entities associated with a physical property region in the database.
Input:
INTEGER rid The physical property region ID for which information is
requested.
Output:
INTEGER count The number of entities for the specified physical property
region.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Counts all entities in the “phys_prop_region” relation in the database for a specified region id.
Example:
Please see db_count_geo_in_region (p. 1264) in the MSC.Acumen, Volume 2: Code Examples.

db_get_geo_in_region ( count, rid, gid, gtype, gsid )

Description:
Gets all geometric entities for a physical property region from the database.
Input:
INTEGER count The number of region IDs for which storage has been
allocated by the calling routine.
INTEGER rid The physical property region for which the geometric entities
are requested.
Output:
INTEGER gid() The IDs of the geometric entities associated with the specified
physical property region.
INTEGER gtype() The type of the geometric entities associated with the
specified physical property region.
INTEGER gsid() The sub-IDs of the geometric entities associated with the
specified physical property region.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Accesses records in the “geometric_region_list” relation by the physical property region id
specified.
Example:
Please see db_get_geo_in_region (p. 1288) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 10 271
Element Properties

db_count_elements_in_region_exp ( rid, count )

Description:
Retrieves the number of elements in a specified region in the database.
Input:
INTEGER rid The region ID for which the element count is requested.
Output:
INTEGER count The number of physical_property_region items stored
in the database.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Counts records in the “element_in_region” relation in the database for one specified region.
Example:
Please see db_count_elements_in_region_exp (p. 1262) in the MSC.Acumen, Volume 2: Code
Examples.

db_create_anl_elm_summary ( acid, atid, etcnt )

Description:
Stores an analysis_element_summary relationship.
Input:
INTEGER acid The analysis code ID.
INTEGER atid The analysis type ID.
INTEGER etcnt(4) The count of element types, one for each element
dimensionality.
Output:
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Uses the analysis_element_summary relationship.
Example:
Please see db_create_anl_elm_summary (p. 1267) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
272
Function Descriptions

db_get_anl_elm_summary ( acid, atid, etcnt )

Description:
Retrieves an analysis_element_summary relationship
Input:
INTEGER acid The analysis code ID.
INTEGER atid The analysis type ID.
Output:
INTEGER etcnt(4) The count of element types, one for each element
dimensionality.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Uses the analysis_element_summary relationship.
Example:
See example for db_create_anl_elm_summary (p. 271). See also db_get_anl_elm_summary
(p. 1284) in the MSC.Acumen, Volume 2: Code Examples.

db_delete_anl_elm_summary ( acid, atid, etcnt )

Description:
Removes an analysis_element_summary relationship.
Input:
INTEGER acid The analysis code ID.
INTEGER atid The analysis type ID.
Output:
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Deletes a analysis_element_summary relationship.
Example:
See example for db_create_anl_elm_summary (p. 271). See also
db_delete_anl_elm_summary (p. 1273) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 10 273
Element Properties

db_create_analysis_elements ( acid, atid, etcnt, etids, etnames )

Description:
Stores a set of analysis_elements relationships.
Input:
INTEGER acid The analysis code ID.
INTEGER atid The analysis type ID.
INTEGER etcnt The count of element types to store.
INTEGER etids() The element type IDs to store.
STRING etnames[]() The element type names to go with the corresponding
ID.
Output:
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Set analysis_elements relationships. Note that the etnames values are actually a denormalized
form of the element_type_name field in the element_type relationship, placed in the
analysis_elements relationship for speed.
Example:
See example for db_create_anl_elm_summary (p. 271). See also
db_create_analysis_elements (p. 1265) in the MSC.Acumen, Volume 2: Code Examples.

db_delete_analysis_elements ( acid, atid, etcnt, etids )

Description:
Removes a set of analysis_elements relationships.
Input:
INTEGER acid The analysis code ID.
INTEGER atid The analysis type ID.
INTEGER etcnt The count of element types to delete.
INTEGER etids() The element type IDs to delete.
Output:
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Removes analysis_elements relationships.
Example:
See example for db_create_anl_elm_summary (p. 271). See also
db_delete_analysis_elements (p. 1271) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
274
Function Descriptions

db_get_analysis_elements ( acid, atid, etcntMax, etcntFound, etids, etnames )

Description:
Retrieves a set of analysis_elements relationships.
Input:
INTEGER acid The analysis code ID.
INTEGER atid The analysis type ID.
INTEGER etcntMax The size that the receiving arrays are dimensioned for.
Output:
INTEGER etcntFound The number of element type IDs and element type
names found. Only the first etcntMax values will
actually be returned.
INTEGER etids() The element type IDs retrieved.
STRING etnames[]() The element type names related to the corresponding
IDs.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Retrieves analysis_elements relationships. Note that the etnames values are actually a
denormalized form of the element_type_name field in the element_type relationship, placed in
the analysis_elements relationship for speed.
Example:
See example for db_create_anl_elm_summary (p. 271). See also db_get_analysis_elements
(p. 1283) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_elem_defn ( acid, atid, eldim )

Description:
Gets all the definitions for all requested elements in get all, get next method.
Input:
INTEGER acid The analysis code ID for the requested element definition.
INTEGER atid The analysis type ID for the requested element definition.
INTEGER eldim The dimensionality for the requested element definition.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
13000117 The query specified has completed.
External Dependencies and Side Effects:
Accesses the “selected_element_type” and “element_type” table in the database.

Main Index
CHAPTER 10 275
Element Properties

Example:
See example for db_create_anl_elm_summary (p. 271). See also db_get_all_elem_defn
(p. 1277) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_elem_defn ( etype_id, ename )

Description:
Gets all the definitions for all requested elements in get all, get next method.
Input:
None.
Output:
INTEGER etype_id The ID of the next element type.
STRING ename[31] The name of the next element type.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
13000117 The query specified has completed.
External Dependencies and Side Effects:
Accesses the “selected_element_type” and “element_type” table in the database.
Example:
See example for db_create_anl_elm_summary (p. 271). See also db_get_next_elem_defn
(p. 1291) in the MSC.Acumen, Volume 2: Code Examples.

db_bulk_get_possible_dof_sets2 ( etid, atid, acid, coc, goc, foc, loc, nbr, dsid )

Description:
This function will retrieve all possible values of the degrees of freedom sets for the specified
input options.
Input:
INTEGER etid This value specifies the id value of the element type.
INTEGER atid This value specifies the id value of the analysis type.
INTEGER acid This value specifies the id value of the analysis code.
INTEGER coc This value specifies the id value of the condense option code.
INTEGER goc This value specifies the id value of the geometric option code.
INTEGER foc This value specifies the id value of the formulation option
code.
INTEGER loc This value specifies the id value of the lamination option
code.

Main Index
276
Function Descriptions

Output:
INTEGER nbr This value returns the number of degrees of freedom set id
values returned in the output value dsid.
INTEGER dsid(nbr) This value returns the unique degrees of freedom set id
values.
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an
error.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches all dof set ids for the input set of parameters.
Example:
Please see db_bulk_get_possible_dof_sets2 (p. 1250) in the MSC.Acumen, Volume 2: Code
Examples.

db_bulk_get_possible_lam_opts2 ( etid, atid, acid, goc, coc, nbr, loc )

Description:
Retrieves all possible values of the laminate option for the specified input options.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
INTEGER goc The ID of the geometric option code selected.
INTEGER coc The ID of the condense option code selected.
Output:
INTEGER nbr The number of laminate option codes that were found for the
above specified set of parameters.
INTEGER loc() The unique laminate option code values that were found for
the above specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches all laminate option codes for the input set of parameters.
Example:
See example for db_bulk_get_possible_dof_sets2 (p. 275). See also
db_bulk_get_possible_lam_opts2 (p. 1255) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 10 277
Element Properties

db_bulk_get_possible_form_opts2 ( etid, atid, acid, goc, coc, loc, nbr, foc )

Description:
Retrieves all possible values of the formulation option for the specified input options.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
INTEGER goc The ID of the geometric option code selected.
INTEGER coc The ID of the condense option code selected.
INTEGER loc The ID of the location option code selected.
Output:
INTEGER nbr The number of formulation option codes found for the above
specified set of parameters.
INTEGER foc() The unique formulation option code values that were found
for the above specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches all formulation option codes for the input set of parameters.
Example:
See example for db_bulk_get_possible_dof_sets2 (p. 275). See also
db_bulk_get_possible_form_opts2 (p. 1252) in the MSC.Acumen, Volume 2: Code Examples.

db_bulk_get_possible_dof_sets1 ( etid, atid, acid, nbr, dsid )

Description:
This function will retrieve all possible values of the degrees of freedom sets for the specified
input options.
Input:
INTEGER etid This value specifies the id value of the element type.
INTEGER atid This value specifies the id value of the analysis type.
INTEGER acid This value specifies the id value of the analysis code.
Output:
INTEGER nbr This value returns the number of degrees of freedom set id
values returned in the output value dsid.
INTEGER dsid(nbr) This value returns the unique degrees of freedom set id values.
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an error.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.

Main Index
278
Function Descriptions

External Dependencies and Side Effects:


Fetches all dof set ids for the input set of parameters.
Example:
Please see db_bulk_get_possible_dof_sets1 (p. 1249) in the MSC.Acumen, Volume 2: Code
Examples.

db_bulk_get_possible_lam_opts1 ( etid, atid, acid, nbr, loc )

Description:
Retrieves all possible values of the laminate option for the specified input options.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
Output:
INTEGER nbr The number of laminate option codes that were found for the
above specified set of parameters.
INTEGER loc() The unique laminate option code values that were found for
the above specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches all laminate option codes for the input set of parameters.
Example:
See example for db_bulk_get_possible_dof_sets1 (p. 277). See also
db_bulk_get_possible_lam_opts1 (p. 1254) in the MSC.Acumen, Volume 2: Code Examples.

db_bulk_get_possible_geo_opts1 ( etid, atid, acid, nbr, goc )

Description:
Retrieves all possible values of the geometric option for the specified input options.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
Output:
INTEGER nbr The number of geometric option codes that were found for
the above specified set of parameters.
INTEGER goc() The unique geometric option code values that were found for
the above specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
Main Index
CHAPTER 10 279
Element Properties

13000002 Unrecoverable database error.


13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches all geometric option codes for the input set of parameters.
Example:
See example for db_bulk_get_possible_dof_sets1 (p. 277). Please see
db_bulk_get_possible_geo_opts1 (p. 1253) in the MSC.Acumen, Volume 2: Code Examples.

db_bulk_get_possible_form_opts1 ( etid, atid, acid, nbr, foc )

Description:
Retrieves all possible values of the formulation option for the specified input options.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
Output:
INTEGER nbr The number of formulation option codes found for the above
specified set of parameters.
INTEGER foc() The unique formulation option code values that were found
for the above specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches all formulation option codes for the input set of parameters.
Example:
See example for db_bulk_get_possible_dof_sets1 (p. 277). See
alsodb_bulk_get_possible_form_opts1 (p. 1251) in the MSC.Acumen, Volume 2: Code
Examples.

db_bulk_get_selected_etops_mat ( etid, atid, acid, goc, foc, loc, dsid, coc, nbr, etop )

Description:
Retrieves all possible values of element topology for the specified input options. All values
must be input for this select.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
INTEGER goc The code for the geometric option if it has been uniquely
determined at point. otherwise, zero.
INTEGER foc The code for the formulation option if it has been uniquely
determined at point. otherwise, zero.
Main Index
280
Function Descriptions

INTEGER loc The code for the laminate option if it has been uniquely
determined at point. otherwise, zero.
INTEGER dsid The ID for the dof set if it has been uniquely determined at
point. otherwise, zero.
Output:
INTEGER nbr The number of formulation option codes found for the above
specified set of parameters.
INTEGER etop() The unique element topology values that were found for the
above specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches all element topologies for the input set of parameters.
Example:
Please see db_bulk_get_selected_etops_mat (p. 1259) in the MSC.Acumen, Volume 2: Code
Examples.

db_bulk_get_possible_matl_dirs ( etid, atid, acid, goc, foc, loc, dsid, coc, mlc, nbr,
mdc )

Description:
Retrieves all possible values of the material directionality option for the specified input options.
If an input option is 0, it does not have a uniquely assigned value yet. The first three parameters
may not be zero.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
INTEGER goc The code for the geometric option if it has been uniquely
determined at point. otherwise, zero.
INTEGER foc The code for the formulation option if it has been uniquely
determined at point. otherwise, zero.
INTEGER loc The code for the laminate option if it has been uniquely
determined at point. otherwise, zero.
INTEGER dsid The ID for the dof set if it has been uniquely determined at
point. otherwise, zero.
INTEGER coc The ID for the condense option if it has been uniquely
determined at point. otherwise, zero.
INTEGER mlc The code for the material linearity if it has been uniquely
determined at point. otherwise, zero.
Output:
INTEGER nbr The number of material directionality codes that were found
for the above specified set of parameters.
INTEGER mdc() The unique material directionality code value that were
found for the above specified set of values.
Main Index
CHAPTER 10 281
Element Properties

INTEGER <Return Value> Returns the success or failure of the routine.


Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches all material directionality codes for the input set of parameters.
Example:
Please see db_bulk_get_possible_matl_dirs (p. 1256) in the MSC.Acumen, Volume 2: Code
Examples.

db_bulk_get_possible_matl_lins ( etid, atid, acid, goc, foc, loc, dsid, coc, mdc, nbr,
mlc )
Description:
Retrieves all possible values of the material linearity option for the specified input options. If an
input option is 0, it does not have a uniquely assigned value yet. The first three parameters may
not be zero.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
INTEGER goc The code for the geometric option if it has been uniquely
determined at point. otherwise, zero.
INTEGER foc The code for the formulation option if it has been uniquely
determined at point. otherwise, zero.
INTEGER loc The code for the laminate option if it has been uniquely
determined at point. otherwise, zero.
INTEGER dsid The ID for the dof set if it has been uniquely determined at
point. otherwise, zero.
INTEGER coc The ID for the condense option if it has been uniquely
determined at point. otherwise, zero.
INTEGER mdc The code for the material directionality if it has been
uniquely determined at point. otherwise, zero.
Output:
INTEGER nbr The number of material linearity codes that were found for
the above specified set of parameters.
INTEGER mlc() The unique material linearity code value that were found for
the above specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches all material linearity codes for the input set of parameters.
Example:
See example for db_bulk_get_possible_matl_dirs (p. 280). See also
db_bulk_get_possible_matl_lins (p. 1258) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
282
Function Descriptions

db_get_all_pp_ids_and_names ( )

Description:
This function will set the cursor to the start of a list of physical property id, name and data type
values.
Input:
None.
Output:
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Remarks:
This function must be called before the db_get_next_pp_ids_and_names (p. 282) function
can be called.
Example:
Please see db_get_all_pp_ids_and_names (p. 1281) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_next_pp_ids_and_names ( pp_id, pp_name, datatype )

Description:
This function will get the next physical property id, name, and data type from the database.
Input:
None.
Output:
INTEGER pp_id This value returns the physical property id value.
STRING pp_name[80] This value returns the physical property name.
INTEGER datatype This value returns the physical property datatype.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
13000142 The MPC was not found in the database.
13000117 The query specified has completed.
External Dependencies and Side Effects:
Accesses records in the phys_prop table in the database.
Remarks:
The PCL function db_get_all_pp_ids_and_names (p. 282) must be called at least once to
establish the list of physical property id, name, and data type values and to set the cursor to
point to the start of the list. Calling the db_get_next_pp_ids_and_names() function in a loop
will then allow the list entries to be retrieved.
Example:
Please see db_get_next_pp_ids_and_names (p. 1294) in the MSC.Acumen, Volume 2: Code
Examples.
Main Index
CHAPTER 10 283
Element Properties

db_set_comp_lam ( mat_name, num_plies, ply_names, thicknesses, orientations,


iconven, offset, offset_def )

Description:
This function will set laminate construction data in the laminate and laminate_layer tables in
the database.
Input:
STRING mat_name[31] This value specifies the name of the material.
INTEGER num_plies This value specifies the number of plies.
STRING ply_names[31*num_plies] This value specifies a list of ply names. See the
remarks below for details on the use of this value.
REAL thicknesses(num_plies) This value specifies a list of ply thicknesses.
REAL orientations(num_plies) This value specifies a list of ply orientations.
INTEGER iconven This value specifies the stacking sequence convention.
REAL offset This value specifies the offset.
LOGICAL offset_def This value specifes, when set to TRUE, that the input
value offset is to be used. When set to FALSE, the
input value offset will be ignored.
Output:
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change
in status or an error.
Remarks:
The input value ply_names is a string that consists of the number of 32 character fields specified
by the input value num_plies. If an individual ply name is less that 32 characters in length it
must be padded by concatinating spaces so that the total name length is 32 characters.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
13000120 The material specified in the query was not found.
13000136 The specified material has an invalid directionality flag.
External Dependencies and Side Effects:
This routine access the material, laminate and laminate_layer tables.
Example:
Please see db_set_comp_lam (p. 1299) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
284
Function Descriptions

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Loads and Boundary Conditions
11
■ General
■ Database

Main Index
286
Function Descriptions

11.1 General

lbc_create (name, type_id, cat_id, dyn_flag, num_ar, ar_id, aplist1, aplist2, fem_flag,
targ_elem, lbc_sf, cid_id, no_data_flag, num_dat, var_id, sv, null_flag,
null_var, datatype, ivalue, rvalue, fldid, dyn_fldid, node_id)

Description:
Create the Loads and Boundary Condition Set ( i.e., for positionally dependent quantities field
references are store not actual values).
Input:
STRING name[] Load/BC Set Name - user specified.
INTEGER type_id Load/BC Type -disp, force, etc.
INTEGER cat_id Category - Nodal, Elem Uni, Elem Var.
INTEGER dyn_flag Dynamic Flag = FA_TRUE if dynamic.
INTEGER num_ar Number of Application Regions.
INTEGER ar_id (2) Appl Region db ID.
STRING aplist1[] Application Region 1 list.
STRING aplist2[] Application Region 2 list.
INTEGER fem_flag (5) FEM Flag = FA_TRUE if FEM entities FEM Flag(4) = app-
reg-couple, FEM Flag (5) = app-reg-order.
INTEGER targ_elem (3) Target Element Dimension.
REAL lbc_sf Lbc Set Scale Factor.
INTEGER cid_id Coordinate System ID.
INTEGER no_data_flag No_Data_Flag = FA_TRUE if no data case is valid.
INTEGER num_dat Number of input data variables.
INTEGER var_id (20) Input Variable Data ID.
INTEGER sv (20) Indicates whether data is scalar or vector.
INTEGER null_flag (20) Null vector flag =1, if null allowed.
INTEGER null_var (20, 3) Flag indicating whether this vector comp is null null_var
= -1 if null, 0 if not null.
INTEGER datatype (20) Indicates datatypes, (e.g. integer, real, field (see
dbcodes.h); DbInt).
INTEGER ivalue (20) Integer value.
REAL rvalue (20, 3) Real value.
INTEGER fldid (20, 3) Field ID.
INTEGER dyn_fldid (20, 3) Dynamic Field ID.
INTEGER node_id (20) Node ID.
Output:
INTEGER <Return Value> See error returned.
Comments:
Entity types and ids will change based on topological description. Displays loads/bcs graphics.
Currently only one application region is being processed.
Error Conditions:
26002020 Load/BC "%A%" already exists. Do you wish to overwrite?
26006004 Dynamic memory allocation error encountered.
Main Index
CHAPTER 11 287
Loads and Boundary Conditions

Example:
Please see lbc_create (p. 1351) in the MSC.Acumen, Volume 2: Code Examples.

lbc_delete ( count, del_id, update_graph )

Description:
Delete the Loads and Boundary Condition Sets (and their related associations - application
region, data, load case association.
Input:
INTEGER count Number of Load/BC Sets to delete.
INTEGER del_id ( count) Load/BC Set Ids.
LOGICAL update_graph If TRUE, then update graphics.
Output:
INTEGER <Return Value> FA_NOERROR success; FA_ERROR Failure.
Comments:
Removes the Load/BC sets from all applicable load cases.
Example:
Please see lbc_delete (p. 1354) in the MSC.Acumen, Volume 2: Code Examples.

lbc_eval_fem_by_lc ( lc_name )

Description:
Given a load case name, get all the lbcs associated with it and check to see if each lbc has any
unevaluated fem_xx_lbcs. If it does then create the appropriate fem_xx_table in the db.
Input:
STRING lc_name[] Load Case Name.
Output:
INTEGER <Return Value> See error returned.
Error Conditions:
3001301 Load Case "%A%" has no Load/BC sets.
3001101 Load Case "%A%" does not exist.
Example:
Please see lbc_eval_fem_by_lc (p. 1356) in the MSC.Acumen, Volume 2: Code Examples.

lbc_eval_fem_lbc ( lbc_id )

Description:
Given an lbc id, check to see if it has any unevaluated fem_xx_lbcs. If it does then create the
appropriate fem_xx_table in the db.
Input:
INTEGER lbc_id Load/BC ID.
Output:
INTEGER <Return Value> See error returned.
Main Index
288
Function Descriptions

Error Conditions:
26002144 The application region for Load/BC Set "%A%" is empty.
Example:
Please see lbc_eval_fem_lbc (p. 1356) in the MSC.Acumen, Volume 2: Code Examples.

lbc_get_sdbx_datatype ( lbc_id, obj_str, meth_str, targ_str, geo_group, sdbx_type,


sdbx_label )

Description:
Given lbc object, method, target element type, and geometry group return the select databox
datatype and label.
Input:
INTEGER lbc_id Load/BC ID.
STRING obj_str[] Load/BC object, e.g., Displacement.
STRING meth_str[] Load/BC Category - Nodal, Element Uniform, Element
Variable.
STRING targ_str[] Target Element Type - Beam, Shell, Solid, PTEAM.
STRING geo_group[] Geometry Group - Geometry or FEM.
Output:
STRING sdbx_type[] Select databox type.
STRING sdbx_label[] Select databox label.
INTEGER <Return Value> See error returned.
Error Conditions:
26002410 "%A%" is an invalid Load/BC target element type.
26002400 "%A%" is an invalid Load/BC type.
Example:
Please see lbc_get_sdbx_datatype (p. 1357) in the MSC.Acumen, Volume 2: Code Examples.

lbc_gm ( )

Description:
Loads/BCs Graphics Manager.
1. Gets the valid groups to which lbcs will be posted.
2. Gets the lbc_types which should be posted from pref form.
3. Filters out the lbc_ids in the current load case which should be posted.
4. Modifies the LBC_IN_GROUP relation as appropriate.
5. Creates the Group Vector Table.
6. Assigns the Group Vector Table to the valid groups.
Input:
none
Output:
INTEGER <Return Value> See error returned.
Error Conditions:
26006004 Dynamic memory allocation error encountered.
Main Index
CHAPTER 11 289
Loads and Boundary Conditions

Example:
Please see lbc_gm (p. 1358) in the MSC.Acumen, Volume 2: Code Examples.

lbc_graphics_defn ( type_id, cat_id, targ_elem_id, nvar, varid, vector_flag, marker,


color, anchor )

Description:
Given an lbc id, get the data in the ss_lbc, sv_lbc, ds_lbc, and/or dv_lbc table.
Input:
INTEGER type_id LBC Type Id - disp, force.
INTEGER cat_id Category - Nodal, Elem Uni, Elem Var.
INTEGER targ_elem_id Target Element Dimension.
Output:
INTEGER nvar Number of input variable (10 max).
INTEGER varid ( ) Input data variable ID.
INTEGER vector_flag ( ) Vector flag = 1, if vector.
INTEGER marker ( ) Graphics symbol.
INTEGER color ( ) Colorbox ID.
INTEGER anchor ( ) Anchor style.
INTEGER <Return Value> Returns success or failure of the routine.
0 = success
-1 = Error occurred
Example:
Please see lbc_graphics_defn (p. 1359) in the MSC.Acumen, Volume 2: Code Examples.

lbc_lp_parse_sca ( data_string, data_type, field_id, null_flag, data_string_value )

Description:
This function will parse a loads and boundary condition data string, verify that it contains valid
scalar or scalar field information, and return the value in the string.
Input:
STRING data_string[] This value specifies a loads and boundary condition
property.
INTEGER data_type This value specifies the property data type.
This value should be set to either 1 to parse integers, 3 to
parse real values, 4 to parse tokens, 5 to parse nodes,
and 7 to parse field values.
If the "datatype" input value is not set to a value of 1 or
5, this function will attempt to parse the "dval" string as
a character, node, or field values based on information
obtained from the string itself.

Main Index
290
Function Descriptions

Output:
INTEGER field_id This value returns the value of id for the scalar field
specified by the input value data_string.
INTEGER null_flag This value returns a non zero value if the input value
data_string represents a valid loads and boundary
condition property that has no data.
REAL data_string_value This value returns the results of the parse of the input
value data_string.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
14000004 LpSublistType: I am being invoked with a NULL list.
26005002 The data entered in databox %I% on the "Input Data" form is invalid.
26005003 Databox %I% on the "Input Data" form requires a Scalar field.
26005001 The data entered in databox %I% on the "Input Data" form cannot be parsed.
Example:
Please see lbc_lp_parse_sca (p. 1360) in the MSC.Acumen, Volume 2: Code Examples.

lbc_lp_parse_vec ( data_string, field_id, null_flag, data_string_value )

Description:
This function will parse a loads and boundary condition vector string, verify that it contains
valid vector or vector field information, and return the value in the string.
Input:
STRING data_string[] This value specifies a loads and boundary condition
property
Output:
INTEGER field_id This value returns the value of id for the scalar field
specified by the input value data_string.
INTEGER null_flag This value returns a non zero value if the input value
data_string represents a valid loads and boundary
condition property that has no data.
REAL data_string_value This value returns the results of the parse of the input
value data_string.
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
14000011 LpSublistAttributeGet: Attempt to get attribute from NULL list.
26005004 Databox %I% on the "Input Data" form requires a Spatial Vector field.
26005001 The data entered in databox %I% on the "Input Data" form cannot be parsed.
Example:
Please see lbc_lp_parse_vec (p. 1361) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 11 291
Loads and Boundary Conditions

lbc_plot_markers ( num_lbcs, lbc_ids, num_grps, grp_ids )

Description:
Creates graphics marker tables for display on groups.
- Filters out the lbc_ids in the current load case which should be posted.
- Modifies the LBC_IN_GROUP relation as appropriate.
- Creates or modifies the Group Vector Table.
- Assigns the Group Vector Table to the valid groups
Input:
INTEGER num_lbcs Number of lbc IDs.
INTEGER lbc_ids ( ) LBC IDs to process.
INTEGER num_grps Number of groups .
INTEGER grp_ids ( ) Group IDs to assign table to.
Output:
INTEGER <Return Value> See error returned.
FA_NOERROR = success
FA_ERROR = failure
Example:
Please see lbc_plot_markers (p. 1362) in the MSC.Acumen, Volume 2: Code Examples.

lbc_show_plot_scalar ( type_name, type_id, dynamic_val, var_name, component,


num_lbcs, lbc_ids, num_grps, grp_ids )

Description:
Main application routine for the Loads/BCs Show Plot Scalar option. A scalar graphics table is
loaded with the specified load/BC and is assigned to the specified groups.
Input:
STRING type_name[] The Load/BC type name.
INTEGER type_id Load/BC type ID.
REAL dynamic_val The value of the dynamic field to evaluate.
STRING var_name[] The name of the variable to be loaded into the scalar
table.
STRING component[] The component of the variable to be loaded into the
scalar table.
INTEGER num_lbcs The number of lbcs to contour.
INTEGER lbc_ids (num_lbcs) The IDs of the lbcs to contour.
INTEGER num_grps The number of groups to assign the scalar table to.
INTEGER grp_ids (num_lbcs) The IDs of the groups to assign the scalar table to.
Output:
INTEGER <Return Value> See error returned.
Error Conditions:
26004001 Unable to assign the scalar table to Group "%A%".
26004003 Invalid component "%A%" was specified. Valid component strings are
"Resultant", "Component1", "Component2", and "Component3".

Main Index
292
Function Descriptions

Example:
Please see lbc_show_plot_scalar (p. 1364) in the MSC.Acumen, Volume 2: Code Examples.

loadcase_create2 (load_case_name, load_case_type, load_case_desc, scale_factor,


lbc_name, priorities, lbc_scales, dynamic_name, mv,
make_current )
Description:
This function creates a new load case in the database.
Input:
STRING load_case_name[] New load case name
STRING load_case_type[] New load case type, can be set to either “Static” or “Time
Dependent”.
STRING load_case_desc[ ] Load case description.
REAL scale_factor Load case scale factor.
STRING lbc_name[]( ) Names of assigned lbcs.
INTEGER priorities() Array of priorities of assigned lbcs.
REAL lbc_scales() Array of lbc scale factors.
STRING dynamic_name[] Dynamic load case name.
REAL mv Flag to indicate if newly created.
LOGICAL make_current Load case should be made the current load case, TRUE if
make current.
Output:
INTEGER <Return Value> This function returns a value of 0 when executed
successfully and a non zero value to indicate a change in
status or an error.
Error Conditions:
-1 This is an internal status condition. There is no
corresponding status message in the message database.
Example:
Please see loadcase_create2 (p. 1365) in the MSC.Acumen, Volume 2: Code Examples.

loadsbcs_get_appl_region_list ( id, region_id, ent_count, geo_str, app_list )

Description:
Gets the application region entities - types, ids, and sub ids (if applicable) from the database.
Input:
INTEGER id Load/BC ID.
INTEGER region_id App Region ID.
INTEGER ent_count Number of entities in appl region.
Output:
STRING geo_str[] Geometry group = Geometry or FEM
STRING app_list[VIRTUAL] Application list.
INTEGER <Return Value> See error returned.
Comments:

Main Index
CHAPTER 11 293
Loads and Boundary Conditions

This routine can be used to return multiple lists by returning the array ARID, increasing the
number of PCL string pointer arguments, and filling them out.
Error Conditions:
26006004 Dynamic memory allocation error encountered.
Example:
Please see loadsbcs_get_appl_region_list (p. 1367) in the MSC.Acumen, Volume 2: Code
Examples.

loadsbcs_lp_coord ( cid_list, cid_id )

Description:
Returns the coordinate system id (Expects there to be only one Coordinate system in the list).
Input:
STRING cid_list[] Coordinate System List.
Output:
INTEGER cid_id Coordinate System ID.
INTEGER <Return Value> See error returned.
Error Conditions:
26002205 No Coordinate Frame chosen. Select one.
26002210 Only one coordinate system is allowed. %I% coordinate systems were input.
26002215 Coordinate Frame List %A% is invalid.
Example:
Please see loadsbcs_lp_coord (p. 1368) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
294
Function Descriptions

11.2 Database

db_bulk_get_lbc_ds ( lbc_id, max, nbr, vid, rv, sc_pos, sc_dyn, scale_factor )

Description:
Fetches unevaluated dynamic scalar lbc data attached to an LBC.
Input:
INTEGER lbc_id The ID of the lbc that this lbc data is attached to.
INTEGER max The max number of dynamic scalar data records that can be
passed back to the caller.
Output:
INTEGER nbr The number of dynamic scalar data records retrieved from
the database.
INTEGER vid() The ID of the definition variable that corresponds to this
scalar data
REAL rv() Scalar data values (real).
INTEGER sc_pos() Field IDs for positional dependent scalars.
INTEGER sc_dyn() Field IDs for dynamic dependent scalars.
REAL scale_factor() LBC set scale factor.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Fetches one or more entries in the “ds_lbc” relation in the database.
Example:
Please see db_bulk_get_lbc_ds (p. 1304) in the MSC.Acumen, Volume 2: Code Examples.

db_bulk_get_lbc_dv ( lbc_id, max, nbr, vid, rv, ve_pos, ve_dyn, nv, scale_factor )

Description:
Fetches unevaluated dynamic vector LBC data attached to an LBC.
Input:
INTEGER lbc_id The ID of the lbc that this lbc data is attached to.
INTEGER max The max number of dynamic vector data records that can be
passed back to the caller.
Output:
INTEGER nbr The number of dynamic vector data records retrieved from
the database.
INTEGER vid() The ID of the definition variable that corresponds to this
vector data.
REAL rv(j, 3) Vector data values (real) {i = vector component;(3) j = vector
number (row nbr)}
INTEGER ve_pos(j, 3) Field IDs for positional dependent vectors {i = vector
component;(3) j = vector number (row nbr)}
Main Index
CHAPTER 11 295
Loads and Boundary Conditions

INTEGER ve_dyn(j, 3) Field IDs for dynamic dependent vectors {i = vector


component;(3) j = vector number (row nbr)}
INTEGER nv(j, 3) Flag indicating whether this vector component contains valid
data. {i = vector component;(3) j = vector number (row nbr)}
a value of -1 denotes a missing value,
a value of 0 denotes not missing
REAL scale_factor() LBC set scale factor
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Fetches one or more entries in the “dv_lbc” relation in the database.
Example:
Please see db_bulk_get_lbc_dv (p. 1306) in the MSC.Acumen, Volume 2: Code Examples.

db_bulk_get_lbc_ss ( lbc_id, max, nbr, vid, rv, sc_pos, scale_factor )

Description:
Fetches unevaluated static scalar LBC data attached to an LBC.
Input:
INTEGER lbc_id The ID of the lbc that this lbc data is attached to.
INTEGER max The max number of static scalar data records that can be
passed back to the caller.
Output:
INTEGER nbr The number of static scalar data records retrieved from the
database.
INTEGER vid() The ID of the definition variable that corresponds to this
scalar data.
REAL rv() Scalar data values (real).
INTEGER sc_pos() Field IDs for positional dependent scalars.
REAL scale_factor() LBC set scale factor.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Fetches one or more entries in the “ss_lbc” relation in the database.
Example:
Please see db_bulk_get_lbc_ss (p. 1308) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
296
Function Descriptions

db_bulk_get_lbc_sv ( lbc_id, max, nbr, vid, rv, ve_pos, nv, scale_factor )

Description:
Fetches unevaluated static vector LBC data attached to an LBC.
Input:
INTEGER lbc_id The ID of the lbc that this lbc data is attached to.
INTEGER max The max number of static vector data records that can be
passed back to the caller.
Output:
INTEGER nbr The number of static vector data records retrieved from the
database.
INTEGER vid() The ID of the definition variable that corresponds to this
vector data.
REAL rv(j, 3) Vector data values (real) {i = vector component (3); j = vector
number (row nbr)}
INTEGER ve_pos(j, 3) Field IDs for positional dependent vectors {i = vector
component (3); j = vector number (row nbr)}
INTEGER nv(j, 3) Flag indicating whether this vector component contains valid
data. {i = vector component (3); j = vector number (row nbr)}
a value of -1 denotes a missing value,
a value of 0 denotes not missing
REAL scale_factor() LBC set scale factor.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000093 Too Many Values Returned for Space Allocated.
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Fetches one or more entries in the “sv_lbc” relation in the database.
Example:
Please see db_bulk_get_lbc_sv (p. 1309) in the MSC.Acumen, Volume 2: Code Examples.

db_count_appl_geo_region ( id, count )

Description:
Retrieves the number of appl_geo_regions stored in the database by lbc_type_id.
Input:
INTEGER id The id of the lbc_type_id with which the appl_geo_regions
are associated
Output:
INTEGER count The number of appl_geo_regions stored in the database
INTEGER <Return Value> Returns the success or failure of the routine
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
Main Index
CHAPTER 11 297
Loads and Boundary Conditions

External Dependencies and Side Effects:


Counts all records in the “appl_geo_region” relation in the database by lbc_type_id.
Example:
Please see db_count_appl_geo_region (p. 1311) in the MSC.Acumen, Volume 2: Code Examples.

db_count_lbc ( count )

Description:
Retrieves the number of lbcs stored in the database.
Input:
none
Output:
INTEGER count The number of appl_geo_regions stored in the database
INTEGER <Return Value> Returns the success or failure of the routine
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Counts all records in the “lbc” relation in the database.
Example:
Please see db_count_lbc (p. 1312) in the MSC.Acumen, Volume 2: Code Examples.

db_count_lbc_appl_region_entity ( id, apprid, count )

Description:
Retrieves the count of entity in each application region, and the application region ids for each
lbc stored in the database.
Input:
INTEGER id The lbc ID for which the region information is requested
Output:
INTEGER apprid(2) The IDs of the application regions stored in the
database. At present two is the maximum.
INTEGER count(2) The number of entities for each appl_geo_regions stored
in the database. at present there is a maximum of two
corresponding to the application region IDs.
INTEGER <Return Value> Returns the success or failure of the routine
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Counts all entities in the “lbc_app_region” relation in the database for a specified lbc_id and
app_region_id.

Main Index
298
Function Descriptions

Example:
Please see db_count_lbc_appl_region_entity (p. 1313) in the MSC.Acumen, Volume 2: Code
Examples.

db_count_lbc_types ( nbr_of_lbcs )

Description:
Returns the total number of distinct lbcs in the database.
Input:
none
Output:
INTEGER nbr_of_lbcs The number of lbc type IDs
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
External Dependencies and Side Effects:
Accesses records in the lbc_type table in the database.
Example:
Please see db_count_lbc_types (p. 1314) in the MSC.Acumen, Volume 2: Code Examples.

db_count_loads_for_element ( elem_id, nbr_of_lbcs )

Description:
Returns the number of loads and boundary conditions for an element.
Input:
INTEGER elem_id The element ID.
Output:
INTEGER nbr_of_lbcs The number of lbcs associated with the element.
INTEGER <Return Value> Returns the success or failure of the routine
External Dependencies and Side Effects:
This routine access the element, fem_ss_lbc, fem_sv_lbc, fem_ds_lbc and fem_dv_lbc tables.
Example:
Please see db_count_loads_for_element (p. 1316) in the MSC.Acumen, Volume 2: Code
Examples.

db_count_load_cases_with_lbc ( lbc_id, num_loadcases )

Description:
Retrieves the number of load cases associated with a lbc.
Input:
INTEGER lbc_id The lbc ID
Output:
INTEGER num_loadcases The number of distinct load cases associated with the above
lbc ID
Main Index
CHAPTER 11 299
Loads and Boundary Conditions

INTEGER <Return Value> Returns the success or failure of the routine


External Dependencies and Side Effects:
Counts records in the “assigned_load_set” relation in the database.
Example:
Please see db_count_load_cases_with_lbc (p. 1314) in the MSC.Acumen, Volume 2: Code
Examples.

db_delete_lbc ( lbc_id )

Description:
Deletes an lbc entry from the database.
Input:
INTEGER lbc_id Id of the lbc to be deleted.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
External Dependencies and Side Effects:
Deletes one record in the “lbc” table in the database, and deletes from any associated lbc entity.
Example:
Please see db_delete_lbc (p. 1317) in the MSC.Acumen, Volume 2: Code Examples.

db_delete_lbc_defn (<lbc_type_id>)

Description:
This function will delete the lbc type definition from the database.
Input:
INTEGER lbc_type_id ID of the lbc type in the database.
Output:
INTEGER <Return Value> Returns 0 for success, otherwise returns the error code.
Error Conditions:
See the Status Message(Ch 11) for information on any error values returned by this function.
Example:
Please see db_delete_lbc_defn (p. 1318) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_appl_geo_regions ( lbc_id )

Description:
Gets all records in the LbcAppRegion table relation for the specified lbc_id from the database,
in get all, get next method. See also db_get_next_appl_geo_region (p. 300).
Input:
INTEGER lbc_id The ID of the lbc for the new records
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine.
Main Index
300
Function Descriptions

Example:
Please see db_get_all_appl_geo_regions (p. 1319) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_next_appl_geo_region ( ar_id, etype, eid, esid )

Description:
Gets next record in the lbcAppRegion table relation for the specified lbc id from the database.
See also db_get_all_appl_geo_regions (p. 299).
Input:
none
Output:
INTEGER ar_id The sequential ID assigned to this application geometry
region.
INTEGER etype The entity type to which this lbc has been applied.
INTEGER eid The entity ID to which this lbc has been applied.
INTEGER esid The entity sub_id to which this lbc has been applied (if
appropriate).
INTEGER <Return Value> Integer indicating success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses records in the “Appl Geo Region” table in the database.
Example:
See example for db_get_all_appl_geo_regions (p. 299). See also
db_get_next_appl_geo_region (p. 1336) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_appl_reg_defns ( lbc_tid )

Description:
Gets all application geometry region definitions for an lbc type definition from the database, in
get all, get next method. See also db_get_next_appl_reg_defn (p. 301)
Input:
INTEGER lbc_tid The ID of the lbc type in the database.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine.
Example:
Please see db_get_all_appl_reg_defns (p. 1320) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 11 301
Loads and Boundary Conditions

db_get_next_appl_reg_defn ( vid, label )

Description:
Gets next application geometry region definition for an lbc type definition from the database.
See also db_get_all_appl_reg_defns (p. 300).
Input:
none
Output:
INTEGER vid The sequential ID assigned to this application geometry
region.
INTEGER label[31] The label to be placed in front of the databox on the “Create
LBC” form.
INTEGER <Return Value> Integer indicating success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
Example:
See example for db_get_all_appl_reg_defns (p. 300). See also db_get_next_appl_reg_defn
(p. 1337) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_lbcs_new ( )

Description:
This function will set up the data required to retrieve all of the information about all of the
LBCs in the memory database.
Input:
none
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine.
Example:
Please see db_get_all_lbcs_new (p. 1326) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_lbcs_new ( id, name, type, cat, eldim, cid, dyn_flag, scaleFactor,


geo_fem, appRegCouple, appRegOrder, equivFlag, acidMod )

Description:
This function will retrieve all of the information about all of the LBCs in the memory database
one structure at a time.
Input:
none
Output:
INTEGER id The ID of the LBC structure.
STRING name[] The name of this lbc table.
Main Index
302
Function Descriptions

INTEGER type The type of the lbc this is.


INTEGER cat The category of lbc this is.
INTEGER eldim(3) The target element dimensionality values.
INTEGER cid The ID of the alternate coordinate frame if there is one.
INTEGER dyn_flag The dynamic/static flag value.
REAL scaleFactor The scale factor value.
INTEGER geo_fem (3) Specifies geo or fem as original lbc app region types.
INTEGER appRegCouple Multi app region coupling option.
INTEGER appRegOrder Multi app region order option.
INTEGER equivFlag The "don't equivalence nodes" flag.
INTEGER acidMod The flag which says that this lbc requires the acid frame
for nodes to be modified.
INTEGER <Return Value> Integer indicating success or failure of the routine.
Example:
See Example for db_get_all_lbcs_new (p. 301). See also db_get_next_lbcs_new (p. 1344) in
the MSC.Acumen, Volume 2: Code Examples.

db_get_all_lbc_names ( )

Description:
Gets all lbc names & types from the database, in get all, get next method. See also
db_get_next_lbc_name (p. 302).
Input:
none
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “lbc” table in the database.
Example:
Please see db_get_all_lbc_names (p. 1321) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_lbc_name ( id, name, type )

Description:
Gets next lbc name & type from the database.
Input:
none

Main Index
CHAPTER 11 303
Loads and Boundary Conditions

Output:
INTEGER id The unique internal ID of the lbc type created in the
database.
STRING name[31] The name of the lbc type being created in the database.
INTEGER type The type ID of the lbc (from the lbc_type table).
INTEGER <Return Value> Integer indicating success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “lbc” table in the database.
Example:
See example for db_get_all_lbc_names (p. 302). See also db_get_next_lbc_name (p. 1338) in
the MSC.Acumen, Volume 2: Code Examples.

db_get_all_lbc_names_by_type ( lbc_typ_id )

Description:
Gets all lbc type names from the database, in get all next method. See also
db_get_next_lbc_name_by_type (p. 303).
Input:
INTEGER lbc_type_id The lbc type ID for the row selected.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “lbc” table in the database.
Example:
Please see db_get_all_lbc_names_by_type (p. 1322) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_next_lbc_name_by_type ( id, name )

Description:
Gets next lbc type name from the database. See also db_get_all_appl_reg_defns (p. 300).
Input:
none
Output:
INTEGER id The unique internal ID of the lbc in the database.
STRING name[31] The name of the lbc being in the database.
Main Index
304
Function Descriptions

INTEGER <Return Value> Integer indicating success or failure of the routine.


Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records for a specified type in the “lbc” table in the database.
Example:
See example for db_get_all_appl_reg_defns (p. 300). See also
db_get_next_lbc_name_by_type (p. 1339) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_lbc_type_defns ( )

Description:
Gets all lbc type definitions from the database, in get all, get next method.See also
db_get_next_lbc_type_defn (p. 304).
Input:
none
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “load case” table in the database.
Example:
Please see db_get_all_lbc_type_defns (p. 1323) in the MSC.Acumen, Volume 2: Code Examples.

db_get_next_lbc_type_defn ( id, name, class, form, gbc, cid, g_sym, sv, nv, nbr_ac,
an_code, defcol, cbid, anstyl )

Description:
Gets next lbc type definition from the database. See also db_get_all_lbc_type_defns (p. 304).
Input:
none
Output:
INTEGER id The unique internal ID of the lbc type created in the database.
STRING name[31] The name of the lbc type being created in the database.
INTEGER class The class of the lbc type to be created. (Structural, Thermal,
Other)
INTEGER form The form of the lbc being created. (Body or Boundary)
INTEGER gbc Flag indicating whether this is a global boundary condition.
Main Index
CHAPTER 11 305
Loads and Boundary Conditions

INTEGER cid Flag indicating whether the lbc can be defined in an alternate
coord frame.
INTEGER g_sym The graphics symbol used to display this lbc.
INTEGER sv Flag indicating whether this lbc is a scalar or vector.
INTEGER nv Flag indicating whether (for vector lbcs) one (or more) of the
components can be null.
INTEGER nbr_ac The number of analysis codes supplied.
INTEGER an_code() List of valid analysis code IDs for this lbc.
INTEGER defcol Default color of associated graphics.
INTEGER cbid Color box ID of associated graphics.
INTEGER anstyl Anchor style of associated graphics.
INTEGER <Return Value> Integer indicating success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “load case” table in the database.
Example:
See example for db_get_all_lbc_type_defns (p. 304). See also db_get_next_lbc_type_defn
(p. 1340) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_lbc_type_names ( )

Description:
Gets all lbc type names from the database, in get all, get next method. See also
db_get_next_lbc_type_name.
Input:
none
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “lbc_type” table in the database.
Example:
Please see db_get_all_lbc_type_names (p. 1325) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
306
Function Descriptions

db_get_next_lbc_type_name ( id, name )

Description:
Gets next lbc type name from the database. See also db_get_all_lbc_type_names (p. 305).
Input:
none
Output:
INTEGER id The unique internal ID of the lbc type in the database.
STRING name[31] The name of the lbc type being in the database.
INTEGER <Return Value> Integer indicating success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “lbc_type” table in the database.
Example:
See example for db_get_all_lbc_type_names (p. 305). See also
db_get_next_lbc_type_name (p. 1342) in the MSC.Acumen, Volume 2: Code Examples.

db_get_all_lbc_var_defns ( id )

Description:
Gets all the lbc variables for an lbc type definition from the database, in get all, get next
method. See also db_get_next_lbc_var_defn (p. 306).
Input:
INTEGER id The lbc type ID for the row selected.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine.
Example:
Please see db_get_all_lbc_var_defns (p. 1325) in the MSC.Acumen, Volume 2: Code Examples
.

db_get_next_lbc_var_defn ( cat, eldim )

Description:
Gets next lbc variable for an lbc type definition from the database. See also
db_get_all_lbc_var_defns (p. 306).
Input:
none
Output:
INTEGER cat The category of this lbc type.
STRING eldim The element shape to get this label.

Main Index
CHAPTER 11 307
Loads and Boundary Conditions

INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
13000117 The query specified has completed.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses records in the “Lbc Variable Defn” table in the database.
Example:
See example under db_get_all_lbc_var_defns (p. 306). See also db_get_next_lbc_var_defn
(p. 1343) in the MSC.Acumen, Volume 2: Code Examples.

db_get_lbc_id ( name, id )

Description:
Retrieves the lbc id associated with the specified lbc name.
Input:
STRING name[31] Pointer to a string containing the name of the lbc.
Output:
INTEGER id Location to receive the resulting value.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000103 No LBC was found.
13000007 An unspecified database error occurred.
Example:
Please see db_get_lbc_id (p. 1328) in the MSC.Acumen, Volume 2: Code Examples.

db_get_lbc_name ( id, name )

Description:
Retrieves the lbc name associated with the specified lbc id.
Input:
INTEGER id Integer containing the ID of the lbc.
Output:
STRING name[31] Pointer to a string where the name of the lbc is to be placed.
INTEGER <Return Value> Returns the success or failure of the routine.
Example:
Please see db_get_lbc_name (p. 1329) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
308
Function Descriptions

db_get_lbc_type_defn ( name, id, class, form, gbc, cid, g_sym, sv, nv, nbr_ac,
an_code, defcol, cbid, anstyl )

Description:
This function will get the attributes of an lbc type definition from the database.
Input:
STRING name[31] This value specifies the name of the lbc type.
Output:
INTEGER id This value returns the id value of the lbc type.
INTEGER class This value returns the class of the lbc type which can be either
structural, thermal, or other.
INTEGER form This value returns the form of the lbc which can be either a body
or a boundary.
INTEGER gbc This value returns an indication stating if the lbc is a global
boundary condition.
INTEGER cid This value returns an indication stating if the lbc can be defined
in an alternate coord frame.
INTEGER g_sym This value returns the graphics symbol used to display this lbc.
INTEGER sv This value returns an indication stating if this lbc is scalar or
vector.
INTEGER nv This value indicates for vector lbcs whether one or more of the
components can be null.
INTEGER nbr_ac The value returns the number of analysis codes applied to this
lbc.
INTEGER an_code(20) This value returns the valid analysis code id values for this lbc.
INTEGER defcol This value returns the default color of the graphics associated
with the lbc.
INTEGER cbid This value returns the color box id of the graphics associated
with the lbc.
INTEGER anstyl This value returns the anchor style of the graphics associated
with the lbc.
INTEGER <Return Value> This function returns a value of 0 when executed successfully
and a non zero value to indicate a change in status or an error.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
13000101 No LBC Definition was found.
External Dependencies and Side Effects:
Accesses all records in the “lbc type” table in the database.
Example:
Please see db_get_lbc_type_defn (p. 1330) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 11 309
Loads and Boundary Conditions

db_get_lbc_var_defn ( lbc_type_id, lbc_category, eldim, label, id )

Description:
Gets the lbc variable defn from the database.
Input:
INTEGER lbc_type_id The ID of the lbc type in the database.
INTEGER lbc_category The ID of the lbc type in the database
INTEGER eldim The dimensionality of the lbc type in the database.
STRING label[] The label of the variable in the database.
Output:
INTEGER id The unique internal ID of the lbc type variable in the
database.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000101 No LBC Definition was found.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Accesses all records in the “lbc_variable_defn” table in the database.
Example:
Please see db_get_lbc_var_defn (p. 1332) in the MSC.Acumen, Volume 2: Code Examples.

db_get_loads_for_element ( nbr_of_lbcs, elem_id, lbc )

Description:
Returns the loads and boundary conditions for an element.
Input:
INTEGER nbr_of_lbcs The amount of memory allocated for the lbc IDs.
INTEGER elem_id The element ID.
Output:
INTEGER lbc() The lbc IDs.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000093 Too Many Values Returned for Space Allocated.
13000157 Fewer values were returned than the amount requested.
External Dependencies and Side Effects:
This routine access the element, fem_ss_lbc, fem_sv_lbc, fem_ds_lbc and fem_dv_lbc tables.
Example:
Please see db_get_loads_for_element (p. 1335) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
310
Function Descriptions

db_get_load_cases_with_lbc ( lbc_id, num_loadcases, loadcase_ids, priority )

Description:
Retrieves the number of load cases associated with an lbc.
Input:
INTEGER lbc_id The ID of the lbcs to which the load cases are associated in
the database.
INTEGER num_loadcases The input/output field containing the maximum number of
load cases on input and the actual number of load cases
retrieved from the database on output.
Output:
INTEGER num_loadcases The input/output field containing the maximum number of
load cases on input and the actual number of load cases
retrieved from the database on output.
INTEGER loadcase_ids() Array of the IDs of the load cases assigned to this lbc id.
INTEGER priority() Priority associated with the assigned load set.
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Retrieves multiple entries from the “assigned_load_case” relation.
Example:
Please see db_get_load_cases_with_lbc (p. 1333) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_valid_cat_by_type ( typid, cat )

Description:
Retrieves all valid categories from the database for a specified type. The maximum number of
categories for a type is three.
Input:
INTEGER typid The specific lbc type for which the category is requested.
Output:
INTEGER cat(3) The categories associated with the specified lbc type.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches the categories associated with specified type from the lbc_variable_defn relation.
Example:
Please see db_get_valid_cat_by_type (p. 1345) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 11 311
Loads and Boundary Conditions

db_get_valid_eldim_by_type_cat ( typid, cat, eldim )

Description:
Retrieves all valid element dimensions for the specified types and categories in the database.
The maximum number of element dimensions is five.
Input:
INTEGER typid The specific lbc type for which the element dimensionality is
requested.
INTEGER cat The categories associated with the specified lbc type.
Output:
INTEGER eldim(5) The types of element dimensionality which correspond to the
input type and category.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches the element dimensionalities associated with specified type and category of lbc from
the lbc_variable_defn relation.
Example:
See example for db_get_valid_cat_by_type (p. 310). See also
db_get_valid_eldim_by_type_cat (p. 1346) in the MSC.Acumen, Volume 2: Code Examples.

db_get_valid_lbc_var_ids ( typid, cat, eldim, count, vid )

Description:
Retrieves all valid element variable ids for the specified combination pf type, category, and
dimensionality specified from the database.
Input:
INTEGER typid The specific lbc type for which the element dimensionality is
requested.
INTEGER cat The categories associated with the specified lbc type.
INTEGER eldim The types of element dimensionality for which the variable
IDs are requested.
INTEGER count Input/Output field which specifies the maximum storage
allocated by the calling routine, and outputs the actual
number of variable IDs fetched if it is not greater than the
count.
Output:
INTEGER count Input/Output field which specifies the maximum storage
allocated by the calling routine, and outputs the actual
number of variable IDs fetched if it is not greater than the
count.
INTEGER vid() Array of variable IDs defined by the combination of items
input.
INTEGER <Return Value> Returns the success or failure of the routine.
Main Index
312
Function Descriptions

Error Conditions:
13000002 Unrecoverable database error.
13000007 An unspecified database error occurred.
External Dependencies and Side Effects:
Fetches the element dimensionalities associated with specified type and category of lbc from
the lbc_variable_defn relation.
Example:
Please see db_get_valid_lbc_var_ids (p. 1348) in the MSC.Acumen, Volume 2: Code Examples.

db_modify_load_case ( id, name, type, desc, nbrlc, lbc, dlcname, mv, priority )

Description:
Modifies a load case in the database.
Input:
INTEGER id The unique internal ID of the load case being modified in the
database.
STRING name[80] The new name of the load case being modified in the
database.
INTEGER type The new type of the load case being modified.
STRING desc[256] The description of the load case being modified.
INTEGER nbrlbc The number of lbcs being attached to this load case.
INTEGER lbc() Array of the IDs of the load\bc set IDs assigned to this load
case.
STRING dlcname[80] The name of the dynamic load case being used as a basis for
this definition. (This field is only applicable if a static load
case is being created from a dynamic load case.)
REAL mv Map variable.
INTEGER priority() The priority for the assigned load set.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000075 Load case name exists.
13000052 Load Case Not Found.
13000002 Unrecoverable database error.
External Dependencies and Side Effects:
Updates an entry in the “load_case” relation in the database and deletes and adds multiple
entries to the “assigned_load_case” relation.
Example:
Please see db_modify_load_case (p. 1349) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
MSC.Acumen, Volume 1: Function Descriptions

CHAPTER
Materials
12
■ Database
■ Laminate Modeler

Main Index
314
Function Descriptions

12.1 Database

db_bulk_get_possible_cond_opts1 (etid, atid, acid, nbr, coc)

Description:
Retrieves all possible values of the condense option for the specified input options.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
Output:
INTEGER nbr The number of condense option codes that were found for the
above specified set of parameters.
INTEGER coc() The unique condense option code values that were found for
the above specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine
Error Conditions:
13000002 Unrecoverable database error
13000007 An unspecified database error occurred
Remarks:
Fetches all condense option codes for the input set of parameters.
Example:
Please see db_bulk_get_possible_cond_opts1 (p. 1370) in the MSC.Acumen, Volume 2: Code
Examples.

db_bulk_get_possible_cond_opts2 (etid, atid, acid, goc, nbr, coc)

Description:
Retrieves all possible values of the condense option for the specified input options.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
INTEGER goc The ID of the geometric option code selected.
Output:
INTEGER nbr The number of condense option codes that were found for the
above specified set of parameters.
INTEGER coc() The unique condense option code values that were found for
the above specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine
Error Conditions:
13000002 Unrecoverable database error
13000007 An unspecified database error occurred
Main Index
CHAPTER 12 315
Materials

Remarks:
Fetches all condense option codes for the input set of parameters.
Example:
Please see db_bulk_get_possible_cond_opts2 (p. 1371) in the MSC.Acumen, Volume 2: Code
Examples.

db_bulk_get_possible_dof_sets (etid, atid, acid, coc, goc, foc, loc, mlc, mdc, nbr, dsid)

Description:
Retrieves all possible values of the condensation option for the specified input options. If an
input option is 0, it does not have a uniquely assigned value yet. The first three parameters
may not be zero.
Input:
INTEGER etid The ID of the element type selected by the user.
INTEGER atid The ID of the analysis type currently selected.
INTEGER acid The ID of the analysis code currently selected.
INTEGER coc The ID for the condense option if it has been uniquely
determined at point. otherwise, zero.
INTEGER goc The code for the geometric option if it has been uniquely
determined at point. otherwise, zero.
INTEGER foc The code for the formulation option if it has been uniquely
determined at point. otherwise, zero.
INTEGER loc The code for the laminate option if it has been uniquely
determined at point. otherwise, zero.
INTEGER mlc The code for the formulation option if it has been uniquely
determined at point. otherwise, zero.
INTEGER mdc The code for the material directionality if it has been uniquely
determined at point. otherwise, zero.
Output:
INTEGER nbr The number of condense option codes that were found for the
above specified set of parameters
INTEGER dsid() The unique dof set ID values that were found for the above
specified set of values.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error
13000007 An unspecified database error occurred
Remarks:
Fetches all dof set ids for the input set of parameters.
Example:
Please see db_bulk_get_possible_dof_sets (p. 1372) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
316
Function Descriptions

db_get_constitutive_model (cid, cm_id, cm_name, linearity_code)

Description:
Gets a constitutive model in the database.
Input:
INTEGER cid The analysis code ID.
INTEGER cm_id The constitutive model ID.
Output:
STRING cm_name[] The constitutive model name.
INTEGER linearity_code The linearity code.
INTEGER <Return Value> Returns the success or failure of the routine
Error Conditions:
None.
Remarks:
This routine retrieves a row in the constitutive_model table in the database.
Example:
See example for db_get_matl_category (p. 318) or db_get_matl_prop_defn (p. 331). See also
db_get_constitutive_model (p. 1394) in the MSC.Acumen, Volume 2: Code Examples.

db_get_valid_const_models_count (cid, atid, mc_id, nbr)

Description:
Returns the number of valid constitutive models for the given analysis code ID, analysis type
ID and material category ID.
Input:
INTEGER cid The analysis code ID.
INTEGER atid The analysis type ID.
INTEGER mc_id The material category ID.
Output:
INTEGER nbr The number of valid constitutive models.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
None.
Remarks:
This routine access the valid_constitutive_models table.
Example:
See example for db_get_valid_const_models (p. 317). See also
db_get_valid_const_models_count (p. 1414) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 12 317
Materials

db_get_valid_const_models (cid, atid, mc_id, cm_id)

Description:
Returns the constitutive model IDs for the given analysis code ID, analysis type ID and
material category ID.
Input:
INTEGER cid The analysis code ID.
INTEGER atid The analysis type ID.
INTEGER mc_id The material category ID.
Output:
INTEGER cm_id() The constitutive model IDs.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
None.
Remarks:
This routine access the valid_constitutive_models table.
Example:
Please see db_get_valid_const_models (p. 1413) in the MSC.Acumen, Volume 2: Code Examples.

db_mo_const_models_specified (mid, cm_id, magics, active)

Description:
Modifies a constitutive model specified in the database.
Input:
INTEGER mid The material ID.
INTEGER cm_id The constitutive model ID.
INTEGER magics(5) The magic numbers ID.
INTEGER active The active flag.
Output:
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000120 The material specified in the query was not found
13000164 The constitutive model was not found in the database
Remarks:
This routine modifies rows in the constitutive_mmodels_specified table in the database.
Example:
Please see db_mo_const_models_specified (p. 1417) in the MSC.Acumen, Volume 2: Code
Examples.

Main Index
318
Function Descriptions

db_delete_matl_const_model (mid, cmid)

Description:
Deletes a constitutive model defn from the database.
Input:
INTEGER mid The ID of the material associated with the material property
value.
INTEGER cmid The ID of the constitutive model.
Output:
INTEGER <Return Value> Integer indicating success or failure of the routine. If the
routine failed, this value contains an indication of the reason.
Error Conditions:
13000002 Unrecoverable database error
13000007 An unspecified database error occurred
Remarks:
Deletes one record in the “matl_const_model_defn” table in the database.
Example:
Please see db_delete_matl_const_model (p. 1380) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_matl_category (cid, mc_id, mc_name, dirctionality)

Description:
Gets a material category definition in the database.
Input:
INTEGER cid The analysis code ID.
INTEGER mc_id The material category defn ID.
Output:
STRING mc_name[] The material category defn name.
INTEGER dirctionality The directionality code.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
None.
Remarks:
This routine retrieves a row in the matl_category table in the database.
Example:
Please see db_get_matl_category (p. 1397) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 12 319
Materials

db_get_valid_mtl_category_cnt (cid, atid, nbr)

Description:
Returns the number of valid material categories for the given analysis code ID and analysis
type ID.
Input:
INTEGER cid The analysis code ID.
INTEGER atid The analysis type ID.
Output:
INTEGER nbr The number of valid material categories.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
None.
Remarks:
This routine access the valid_material_categories table.
Example:
Please see db_get_valid_mtl_category_cnt (p. 1416) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_valid_mtl_categories (cid, atid, mc_id)

Description:
Returns the valid material categories for the given analysis code ID and analysis type ID.
Input:
INTEGER cid The analysis code ID.
INTEGER atid The analysis type ID.
Output:
INTEGER mc_id() The material category ids.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
None.
Remarks:
This routine access the valid_material_categories table.
Example:
See example for db_get_valid_mtl_category_cnt (p. 319). See also
db_get_valid_mtl_categories (p. 1415) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
320
Function Descriptions

db_create_mtl_allowable_magics (cid, mc_id, magic_category_id, magic_alias_id,


nbr)

Description:
Creates ’nbr’ records in the allowable_magic_prop table.
Input:
INTEGER cid The analysis code ID.
INTEGER mc_id The material category ID. See Material Categories (p. 389) in
the PCL and Customization.
INTEGER magic_category_id The magic category ID. See Material Options and Material
Option Categories (p. 393) in the PCL and Customization.
INTEGER magic_alias_id() The magic (ooh) alias ID. See
db_create_mtl_magics_options (p. 394) in the PCL and
Customization.
INTEGER nbr The number of magic aliases.
Output:
INTEGER <Return Value> Returns the success or failure of the routine
Error Conditions:
None.
Remarks:
This routine access the allowable_magic_prop table.
Example:
Please see db_create_mtl_allowable_magics (p. 1376) in the MSC.Acumen, Volume 2: Code
Examples.

db_get_mtl_allowable_magic_cnt (code_id, matl_cat_id, magic_category_id, nbr)

Description:
Returns the number of allowable magic properties for the given magic_category_id, code_id,
and matl_cat_id
Input:
INTEGER code_id The analysis code ID.
INTEGER matl_cat_id The material category ID.
INTEGER magic_category_id The magic category ID.
Output:
INTEGER nbr The number of magic aliases.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
None.
Remarks:
This routine access the allowable_magic_prop table.
Example:
Please see db_get_mtl_allowable_magic_cnt (p. 1402) in the MSC.Acumen, Volume 2: Code
Examples.
Main Index
CHAPTER 12 321
Materials

db_count_options (goc, coc, loc, foc, dsid, etop)

Description:
Retrieves a count of the number of distinct geometric (or laminate, or...) option codes.
Input:
None.
Output:
INTEGER goc The count of geometric options.
INTEGER coc The count of condense options.
INTEGER loc The count of laminate options.
INTEGER foc The count of formulation options.
INTEGER dsid The count of dof sets.
INTEGER etop The count of element topologies.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000002 Unrecoverable database error
13000007 An unspecified database error occurred
Remarks:
Counts all of the listed option codes.
Example:
Please see db_count_options (p. 1375) in the MSC.Acumen, Volume 2: Code Examples.

db_get_mtl_allowable_magics (code_id, matl_cat_id, magic_category_id,


magic_alias_id)

Description:
Returns the number of allowable magic properties for the given magic_category_id, cid, and
mc_id.
Input:
INTEGER code_id The analysis code ID.
INTEGER matl_cat_id The material category ID.
INTEGER magic_category_id The magic category ID.
Output:
INTEGER magic_alias_id() The magic alias ids.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
None.
Remarks:
This routine access the allowable_magic_prop table.
Example:
See example for db_get_mtl_allowable_magic_cnt (p. 320). See also
db_get_mtl_allowable_magics (p. 1403) in the MSC.Acumen, Volume 2: Code Examples.

Main Index
322
Function Descriptions

db_get_mtl_magics (analysis_code_id, analysis_type_id, matl_category_id,


constit_model_id, magic_category_id)

Description:
Returns the material magic categories for the given cid, mc_id, and cm_id
Input:
INTEGER analysis_code_id The analysis code ID.
INTEGER analysis_type_id The analysis type ID.
INTEGER matl_category_id The material category ID.
INTEGER constit_model_id The constitutive model ID.
Output:
INTEGER magic_category_id() The magic category ids.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
None.
Remarks:
This routine access the matl_magic table.
Example:
Please see db_get_mtl_magics (p. 1404) in the MSC.Acumen, Volume 2: Code Examples.

db_get_mtl_magics_count (analysis_code_id, analysis_type_id, matl_category_id,


constit_model_id, nbr)

Description:
Returns the number of material magic properties for the given analysis_code_id,
analysis_type_id, matl_category_id, and constit_model_id
Input:
INTEGER analysis_code_id The analysis code ID.
INTEGER analysis_type_id The analysis type ID.
INTEGER matl_category_id The material category ID.
INTEGER constit_model_id The constitutive model ID.
Output:
INTEGER nbr The number of magic categories.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
None.
Remarks:
This routine access the matl_magic table.
Example:
See example for db_get_mtl_magics (p. 322). See also db_get_mtl_magics_count (p. 1406)
in the MSC.Acumen, Volume 2: Code Examples.

Main Index
CHAPTER 12 323
Materials

db_get_mtl_magics_defn (analysis_code_id, analysis_type_id, magic_category_id,


magic_label)

Description:
Returns the magic label given the analysis code ID and the magic category.
Input:
INTEGER analysis_code_id The analysis code ID.
INTEGER analysis_type_id The analysis type ID.
INTEGER magic_category_id The magic category ID.
Output:
STRING magic_label[] The magic label.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Conditions:
13000086 No Records Found
Remarks:
This routine access the matl_magic_definition table.
Example:
See example for db_get_mtl_magics (p. 322). See also db_get_mtl_magics_defn (p. 1407) in
the MSC.Acumen, Volume 2: Code Examples.

db_get_mtl_magics_options (analysis_code_id, magic_alias_id, magic_name)

Description:
Returns the magic alias given the analysis code ID and the magic alias.
Input:
INTEGER analysis_code_id The analysis code ID.
INTEGER magic_alias_id The magic alias ID.
Output:
STRING magic_name[] The magic alias.
INTEGER <Return Value> Returns the success or failure of the routine.
Error Con