omni_modify_definition(3sh1) — Subroutines
Name
omni_modify_definition − The omni_modify_definition procedure modifies the value of a specified attribute of a specified definition. The address of the new attribute value is passed as a parameter to the routine.
Omni_modify_definition modifies the values of both single-valued and multi-valued attributes. In the case of multi-valued attributes, omni_modify_definition is used much like omni_get_handle_list. Each call to omni_modify_definition specifies one value. The value of the ATTRIBUTE parameter must specify the address of the attribute on the first call, and must be NULL thereafter. A value of NULL for the ATTRIBUTE parameter indicates that the next value must be specified.
Omni_end_list must be called after modifying a list to free space allocated for bookkeeping by DEComni.
Syntax
extern unsigned long int omni_modify_definition (
omni_l_handle def_handle,
omni_l_attributes ∗attribute,
omni_l_context ∗context,
void ∗value,
unsigned long int value_length);
Arguments
def_handleaccess: read only mechanism: by value Def_handle specifies the handle of the definition to be modified. The value of this parameter is one of the following:
•VMD Handle
•Domain Handle
•PI Handle
•Named Variable Handle
•Unnamed Variable Handle
•MMS Named Type Handle
•Application Named Type Handle
•MMS Type Specification Handle
•Application Type Specification Handle
•MMS Structure Component
•Application Structure Component
•Message Handle
attributeaccess: read only mechanism: by reference Attribute specifies the address of a variable whose value is the attribute to modify or NULL to specify multiple valued attribute.
contextaccess: read/write mechanism: by reference optional argument Context is the address of a variable of type omni_l_context. This parameter is used by DEComni only if you modify a multi-valued attribute.
The value of context must be initialized to NULL. In general, the value of the context must be modified when as many values as required have been retrieved from a multi-valued attribute. In this case, omni_end_list must be called to free any unnecessary space allocated by DEComni. The value of the context must then be reset to zero.
valueaccess: read only mechanism: by reference Value is the address of a buffer that contains the new attribute value.
value_lengthaccess: read only mechanism: by reference The length of the attribute value buffer in bytes.
Usage Notes
A definition is not usable until the value of its SCOPE attribute has been modified. The scope of a definition can be modified only once, and each class of definition must have a particular set of attributes modified before its scope can be modified.
The attributes supported for each definition class, the expected type of attribute value, and the default value are listed in the following tables.
The following table shows VMD values.
| VMD Attributes | Expected Data Type | Defaults |
| omni_c_attr_name | omni_t_mms_id_nt | None |
| omni_c_attr_appl_simple_name | omni_t_appl_simple_name_wc | Name of VMD |
| omni_c_attr_vmd_max_segment | Longword | 512 |
| omni_c_attr_vmd_max_srv_calling | Longword | 5 |
| omni_c_attr_vmd_max_srv_called | Longword | 5 |
| omni_c_attr_vmd_nesting | Byte | 10 |
| omni_c_attr_vmd_param_supported | omni_a_param_cbb | See note |
| omni_c_attr_vmd_srv_supported | omni_a_services_supported | See note |
| omni_c_attr_vmd_version | Word | 1 |
| omni_c_attr_vendor | omni_t_visible_str_127 | "" |
| omni_c_attr_model | omni_t_visible_str_127 | "" |
| omni_c_attr_revision | omni_t_visible_str_127 | "" |
| omni_c_attr_scope | null | None |
| omni_c_attr_description | omni_t_description | "" |
| omni_c_attr_user_param | Longword | None |
| omni_c_attr_logical_status | Longword | None |
| omni_c_attr_physical_status | Longword | None |
| omni_c_attr_local_detail | omni_a_local_detail | None |
| omni_osap_c_attr_notopen_srvspt | ||
| omni_osap_a_notopen_srvspt | See note | |
| omni_osap_c_attr_cpu_id | Longword | See note |
| omni_osh1_c_attr_notopen_srvspt | ||
| omni_osh1_a_notopen_srvspt | See note |
Usage Notes
Requirements and restrictions are as follows:
•In order to modify the value of the scope attribute of the VMD definition, the value of the Name attribute must already be specified.
•The value of the Version attribute must be one (1) (MMS_IS) or zero (0) (MMS_DIS).
•The scope of a VMD definition must be specified as NULL.
•The omni_osap_c_attr_cpu_id must be assigned the same value as specified in the configuration of the remote device. The default value is 1.
•In SINEC-H1, if you want to use Variable Access, Program Invocation and Domain Services, you must specify the omni_c_attr_model attribute.
•The following are defaults for omni_c_attr_vmd_param_supported, omni_c_attr_vmd_srv_supported and omni_osap_c_attr_notopen_srvspt.
Default for omni_c_attr_vmd_param_supported:
(0) STR1 (Arrays) TRUE
(1) STR2 (Structures) TRUE
(2) VNAM (Named Variables) TRUE
(3) VALT (Alternate Access) TRUE
(4) VADR (Unnamed Variables) TRUE
(5) VSCA (Scattered Access) FALSE
(6) TPY (Third Party) FALSE
(7) VLIS (Named Variable List) FALSE
(8) REAL (Real) FALSE
(9) AKEC (Acknowledgment Event Conditions) FALSE
(10) CEI (Evaluation Interval) FALSE
Default for omni_c_attr_srv_supported:
/∗ vmd support services ∗/
(0) Status TRUE
(1) GetNameList FALSE
(2) Identify TRUE
(3) Rename FALSE
/∗ variable access services ∗/
(4) Read TRUE
(5) Write TRUE
(6) GetVariableAccessAttributes FALSE
(7) DefineNamedVariable FALSE
(8) DefineScatteredAccess FALSE
(9) GetScatteredAccessAttributes FALSE
(10) DeleteVariableAccess FALSE
(11) DefineNamedVariableList FALSE
(12) GetNamedVariableListAttributes FALSE
(13) DeleteNamedVariableList FALSE
(14) DefineNamedType FALSE
(15) GetNamedTypeAttributes FALSE
(16) DeleteNamedType FALSE
/∗ operator communication services ∗/
(17) Input FALSE
(18) Output FALSE
/∗ semaphore management services ∗/
(19) TakeControl FALSE
(20) RelinquishControl FALSE
(21) DefineSemaphore FALSE
(22) DeleteSemaphore FALSE
(23) ReportSemaphoreStatus FALSE
(24) ReportPoolSemaphoreStatus FALSE
(25) ReportSemaphoreEntryStatus FALSE
/∗ domain management services ∗/
(26) InitiateDownloadSequence FALSE
(27) DownloadSegment TRUE
(28) TerminateDownloadSequence TRUE
(29) InitiateUploadSequence FALSE
(30) UploadSegment FALSE
(31) TerminateUploadSequence FALSE
(32) RequestDomainDownload TRUE
(33) RequestDomainUpload TRUE
(34) LoadDomainContent FALSE
(35) StoreDomainContent FALSE
(36) DeleteDomain FALSE
(37) GetDomainAttributes FALSE
/∗ program invocation management services ∗/
(38) CreateProgramInvocation FALSE
(39) DeleteProgramInvocation FALSE
(40) Start FALSE
(41) Stop FALSE
(42) Resume FALSE
(43) Reset FALSE
(44) Kill FALSE
(45) GetProgramInvocationAttributes FALSE
/∗ file management services ∗/
(46) ObtainFile FALSE
/∗ event management services ∗/
(47) DefineEventCondition FALSE
(48) DeleteEventCondition FALSE
(49) GetEventConditionAttributes FALSE
(50) ReportEventConditionStatus FALSE
(51) AlterEventConditionmonitoring FALSE
(52) TriggerEvent FALSE
(53) DefineEventAction FALSE
(54) DeleteEventAction FALSE
(55) GetEventActionAttributes FALSE
(56) ReportEventActionStatus FALSE
(57) DefineEventEnrollment FALSE
(58) DeleteEventEnrollment FALSE
(59) AlterEventEnrollment FALSE
(60) ReportEventEnrollmentStatus FALSE
(61) GetEventEnrollmentAttributes FALSE
(62) AcknowledgeEventNotification FALSE
(63) GetAlarmSummary FALSE
(64) GetAlarmEnrollmentSummary FALSE
/∗ journal management services ∗/
(65) ReadJournal FALSE
(66) WriteJournal FALSE
(67) InitializeJournal FALSE
(68) ReportJournalStatus FALSE
(69) CreateJournal FALSE
(70) DeleteJournal FALSE
/∗ vmd support services ∗/
(71) GetCapabilityList FALSE
/∗ file management services ∗/
(72) FileOpen FALSE
(73) FileRead FALSE
(74) FileClose FALSE
(75) FileRename FALSE
(76) FileDelete FALSE
(77) FileDirectory FALSE
/∗ unconfirmed services ∗/
(78) UnsolicitedStatus TRUE
(79) InformationReport TRUE
(80) EventNotification FALSE
(81) AttachToEventCondition FALSE
(82) AttachToSemaphore FALSE
/∗ additional services ∗/
(83) Conclude TRUE
(84) Cancel FALSE
Default for omni_osap_c_attr_vmd_notopen_srvspt:
/∗ serial transfer services ∗/
(0) Read TRUE
(1) Write TRUE
(2) Exchange TRUE
The following table shows Domain values.
| Domain Constants | Data Type | Defaults |
| omni_c_attr_name | omni_t_mms_id_nt | None |
| omni_c_attr_capability_file | omni_t_file_name | omni_domains: [VMD]domain.cap where VMD is the name of the parent VMD and domain is the domain name |
| omni_c_attr_dom_content_file | omni_t_file_name | "" |
| omni_c_attr_deletable | omni_b_boolean | True |
| omni_c_attr_sharable | omni_b_boolean | False |
| omni_c_attr_scope | omni_l_handle | None |
| omni_c_attr_description | omni_t_description | "" |
| omni_c_attr_user_param | Longword | None |
| omni_osh1_c_attr_blk_addr_list | omni_t_address_str | See note |
Usage Notes
Requirements and restrictions are as follows:
•In order to modify the value of the scope attribute, the Name of the Domain definition must already be specified.
•The run-time object definition facility does not restrict the sharing of a domain that has been specified as not terrible.
•The value of the scope attribute must be a VMD handle.
•If you do not specify the omni_osh1_c_attr_blk_addr_list attribute, the Domain is the entire memory of the PLC.
The following table shows PI values.
| PI Constants | Data Types | Defaults |
| omni_c_attr_name | omni_t_mms_id_nt | None |
| omni_c_attr_ref_dom_names | omni_l_handle | "" |
| omni_c_attr_exec_arg | omni_t_visible_str_255_nt | "" |
| omni_c_attr_deletable | omni_b_boolean | True |
| omni_c_attr_reusable | omni_b_boolean | False |
| omni_c_attr_monitor | omni_b_boolean | iiomni_c_pimnt_not_present |
| omni_c_attr_scope | omni_l_handle | None |
| omni_c_attr_description | omni_t_description | None |
| omni_c_attr_user_param | longword | None |
| omni_c_attr_ec_ref | omni_r_mms_object_name | None |
| omni_c_attr_ea_ref | omni_r_mms_object_name | None |
| omni_c_attr_ee_ref | omni_r_mms_object_name | None |
Usage Notes
Requirements and restrictions are as follows:
•In order to modify the value of the scope attribute, the Name of the PI and at least one Referenced Domain must already be specified.
•The value of the scope attribute must be a VMD handle.
•The values of the Referenced Domains attribute must be the handles of committed domains.
•The Domains referenced by the Program Invocation must all have the same VMD as a parent. Additionally, the Program Invocation must have the same parent as the Domains it references.
The following table shows Named Variable values.
| Named Variable | Data Types | Defaults |
| omni_c_attr_name | omni_t_mms_id_nt | None |
| omni_c_attr_app_type_desc | omni_l_handle | None |
| omni_c_attr_deletable | omni_b_boolean | True |
| omni_c_attr_scope | omni_l_handle | None |
| omni_c_attr_description | omni_t_description | "" |
| omni_c_attr_user_param | Longword | None |
Usage Notes
Requirements and restrictions are as follows:
•In order to modify the value of the scope attribute, the values of the Name and the Application Type Description attributes must already be specified.
•The value of the scope attribute of a named variable definition must be the handle of a domain or a VMD.
•If the value of the Application Type Description Attribute is an Application Named Type handle, then the Application Named Type definition must be committed. Additionally, the Named Variable and the Application Named Type definitions must reside on the same VMD definition.
•If the value of the Application Type Description attribute is an Application Type Specification handle, then the Application Type Specification may not already be referenced by any other definition.
The following table shows Unnamed Variable values.
| Unnamed Variables | Data Types | Defaults |
| omni_c_attr_name | omni_t_mms_id_nt | None |
| omni_c_attr_app_type_desc | omni_l_handle | None |
| omni_c_attr_address_type | omni_l_address_types | None |
| omni_c_attr_address_string | omni_t_address_str | None |
| omni_c_attr_address_number | Longword | None |
| omni_c_attr_supply_type_spec | omni_b_boolean | True |
| omni_c_attr_scope | omni_l_handle | None |
| omni_c_attr_description | omni_t_description | "" |
| omni_c_attr_user_param | Longword | None |
Usage Notes
Requirements and restrictions are as follows:
•In order to modify the value of the scope attribute, the values of the Name, Address Type and either Address String or Address Number, and Application Type Description attributes must be already specified.
•The value of the scope attribute of an Unnamed Variable definition must be the handle of a VMD.
•If the value of the Application Type Description Attribute is an Application Named Type handle, then the Application Named Type must be committed. Additionally, the Named Variable and the Application Named Type definitions must reside on the same VMD definition.
•If the value of the Application Type Description attribute is an Application Type Specification handle, then the Application Type Specification may not already be referenced by any other definition.
•The value of the Address Type attribute must be modified before the value of either the Address String or Address Number attribute.
•DEComni allows the user to modify the value of the Address Type attribute even after the value of the Address String or Address Number attribute has been modified, DEComni does not compare the value of the Address Type attribute with the type of the address.
The following table shows MMS Named Type values.
| MMS Named Types | Data Types | Defaults |
| omni_c_attr_name | omni_t_mms_id_nt | None |
| omni_c_attr_mms_type_desc | omni_l_handle | None |
| omni_c_attr_deletable | omni_b_boolean | True |
| omni_c_attr_scope | omni_l_handle | None |
| omni_c_attr_description | omni_t_description | "" |
| omni_c_attr_user_param | Longword | None |
Usage Notes
Requirements and restrictions are as follows:
•In order to modify the value of the scope attribute, the values of the Name and MMS Type Description Attributes must already be specified.
•The value of the scope attribute of an MMS Named Type definition must be the handle of a domain or a VMD definition.
•If the value of the MMS Type Description Attribute is an MMS Named Type handle, then the referred to MMS Named Type must already be committed. Additionally, both MMS Named Type definitions must ultimately reside on the same VMD definition.
•If the value of the MMS Type Description Attribute is an MMS Type Specification handle, then the MMS Type Specification may not already be referenced by any other definition. When the MMS Named Type definition is ready to be committed, its parent VMD must be the same as the parent VMDs of any MMS Named Type definitions referred to by the MMS Type Specification definition.
The following table shows Application Named Type values.
| Application Named Types | Data Types | Defaults |
| omni_c_attr_name | omni_t_mms_id_nt | None |
| omni_c_attr_app_type_desc | omni_l_handle | None |
| omni_c_attr_mms_named_type | omni_l_handle | None |
| omni_c_attr_scope | omni_l_handle | None |
| omni_c_attr_description | omni_t_description | "" |
| omni_c_attr_user_param | Longword | None |
Usage Notes
Requirements and restrictions are as follows:
•In order to modify the value of the scope attribute, the values of the Name, MMS Named Type, and Application Type Description Attributes must already be specified.
•The value of the scope attribute of an Application Named Type Definition must be the handle of a domain or a VMD definition.
•If the value of the Application Type Description Attribute is an Application Named Type Handle, then the Application Named Type definition must already be committed. Additionally, the Application Named Type Definitions must ultimately reside on the same VMD definition.
•If the value of the Application Type Description Attribute is an Application Type Specification Handle, then the Application Type Specification definition cannot already be referenced by any other definition. Additionally, the Application Named Type definition must reside on the same VMD as any Application Named Type definition referred to by the Application Type Specification definition.
•The value of the MMS Named Type Attribute must be the handle of a committed MMS Named Type Definition. The MMS Named Type Definition and the Application Named Type Definition must ultimately reside on the same VMD Definition.
The following table shows MMS Type Specification values.
| MMS Type | Data Type | Default |
| omni_c_attr_mms_type | omni_l_mms_data_types | None |
| omni_c_attr_array_elem_num | Longword | 0 |
| omni_c_attr_array_elem_mms_type | omni_l_handle | None |
| omni_c_attr_simple_size | longword | 0 |
| omni_c_attr_simple_varying | omni_b_boolean | False |
| omni_c_attr_date_included | omni_b_boolean | False |
| omni_c_attr_description | omni_t_description | None |
| omni_c_attr_user_param | Longword | None |
Usage Notes
Requirements and restrictions are as follows:
•The value of the MMS Type Attribute must be modified before other attributes may be modified. The MMS Type Attribute may be modified once.
•An MMS Type Specification is valid when the following is true:
•The value of the MMS Type Attribute has been specified
•If the value of the MMS Type Attribute is omni_c_mmstype_array then the value of omni_c_attr_array_elem_num attribute has been specified, or
•If the value of the MMS Type Attribute is omni_c_mmstype_structure then at least one structure component has been specified for the type specification.
•The MMS Type Specification must be valid before it can be referenced by another definition. Additionally, an MMS Type Specification may only be referenced once by either another MMS Type Specification definition or by an MMS Named Type Definition.
•The value of the MMS Type Attribute is a constant from the omni_c_mmstype_∗ enumeration in omni_defs. The following constants are acceptable values:
•omni_c_mmstype_array
•omni_c_mmstype_structure
•omni_c_mmstype_boolean
•omni_c_mmstype_bit_str
•omni_c_mmstype_integer
•omni_c_mmstype_unsigned
•omni_c_mmstype_floating_point
•omni_c_mmstype_octet_str
•omni_c_mmstype_visible_str
•omni_c_mmstype_generalized_time
•omni_c_mmstype_binary_time
The following table shows Application Type Specification values.
| Application Type | Data Type | Defaults |
| omni_c_attr_app_type | omni_l_app_data_type | None |
| omni_c_attr_mms_type_spec | omni_l_handle | None |
| omni_c_attr_array_elem_num | Longword | None |
| omni_c_attr_array_elem_app_type | omni_l_handle | None |
| omni_c_attr_array_low | Longword | None |
| omni_c_attr_simple_size | Longword | None |
| omni_c_attr_description | omni_t_description | None |
| omni_c_attr_user_param | Longword | None |
Usage Notes
Requirements and restrictions are as follows:
•The value of the Application Type Attribute must be modified before other attributes may be modified. The Application Type Attribute may be modified once.
•
An Application Type Specification definition is valid when:
•The value of the Application Type Attribute has been specified
•If the value of the Application Type Attribute is omni_c_apptype_array then the values of the omni_c_attr_array_elem_app_type attribute and the omni_c_attr_array_elem_num attribute have been specified, or
•If the value of the Application Type Attribute is omni_c_apptype_structure then at least one structure component has been specified for the type specification definition
•The value of the MMS Type Specification Attribute has been specified
•The Application Type Specification is not already referenced by another definition
•The Application Type Specification definition must be valid before it can be referenced by another definition. Additionally, an Application Type Specification may only be referenced by one definition.
•The value of the App Type Attribute is a constant from the omni_c_apptype_∗ enumeration. The following constants are acceptable values:
•omni_c_apptype_array
•omni_c_apptype_structure
•omni_c_apptype_boolean
•omni_c_apptype_bit_str
•omni_c_apptype_integer
•omni_c_apptype_unsigned
•omni_c_apptype_f_float
•omni_c_apptype_terminated_str
•omni_c_apptype_word_counted_str
•omni_c_apptype_scalar_str
•omni_c_apptype_omni_time
•omni_c_apptype_boolean_array
The following table shows MMS Structure Component values.
| MMS Structure Component | Data Type | Default |
| omni_c_attr_name | omni_t_mms_id_nt | None |
| omni_c_attr_mms_type_desc | omni_l_handle | None |
| omni_c_attr_description | omni_t_description | None |
| omni_c_attr_user_param | Longword | None |
| omni_c_attr_scope | omni_l_handle | None |
Usage Notes
Requirements and restrictions are:
•In order to modify the value of the scope attribute, the values of the Name and MMS Type Description attributes must already be specified.
•The value of the scope attribute of an MMS Structure Component Definition is the handle of an MMS Type Specification Definition whose MMS Type Attribute has a value of omni_c_mmstype_structure.
•If the value of the MMS Type Description Attribute is an MMS Named Type handle, then the MMS Named Type definition must be committed. Additionally, the MMS Named Type definition and the MMS structure component must ultimately reside on the same VMD definition.
•If the value of the MMS Type Description attribute is an MMS Type Specification Handle, then the MMS Type Specification may not already be referenced by any other definition.
The following table shows App Structure Component values.
| App Structure Component | Value | Default |
| omni_c_attr_name | omni_t_app_id_nt | None |
| omni_c_attr_description | omni_t_description | None |
| omni_c_attr_app_type_desc | omni_l_handle | None |
| omni_c_attr_mms_struct_comp | omni_l_handle | None |
| omni_c_attr_scope | omni_l_handle | None |
| omni_c_attr_user_param | Longword | None |
Usage Notes
Requirements and restrictions are as follows:
•In order to modify the value of the scope attribute, the values of the Name, App Type Description, and MMS Type Specification Attributes must already be specified.
•The value of the scope attribute of an Application Structure Component Definition is the handle of an Application Type Specification Definition whose Application Type Attribute has a value of omni_c_apptype_structure.
•If the value of the Application Type Description Attribute is an Application Named Type Handle, then the Application Named Type definition must be committed. Additionally, the Application Named Type Definition and the Application Structure Component definition must reside on the same VMD definition.
•If the value of the Application Type Description Attribute is an Application Type Specification Handle, then the Application Type Specification definition cannot already be referenced by any other definition.
The following table shows message data information.
| Attributes | Expected Data Types |
| omni_c_attr_name | omni_t_mms_id_nt |
| omni_c_attr_description | omni_t_description |
| omni_c_attr_scope | omni_l_handle |
| omni_c_attr_msg_length | Word |
Usage Notes
•The value of the scope attribute is the handle of a VMD definition.