Description of the DP Functions, Data, and
4.1 List of Functions of the CP 5613 and CP 5614
4.1.12 DP_global_ctrl
Purpose
With this function, a global control command can be sent to one or more slaves.
Note
Slaves are assigned to a slave group when the DP database is configured. A slave evaluates the global control command only when it is assigned to one of the addressed groups by the configuration.
Syntax
DPR_DWORD DP_global_ctrl(
DPR_DWORD user_handle, // in
DPR_WORD slv_add, // in
DPR_BYTE command, // in
DPR_BYTE group, // in
DP_ERROR_T *error ); // out
DP Base Programming Interface for CP 5613/CP 5614
C79000-G8976-C139-09 133
Parameters
Name Description
user_handle User handle assigned with the DP_open call.
slv_add Address of the slave or group address (DP_BROADCAST_ADR)
command Here, the following global control commands can be specified (they can also be ORed):
● DP_SYNC: freeze the output bytes
● DP_UNSYNC: cancel the DP_SYNC command
● DP_FREEZE: the states of the inputs are read in
and frozen
● DP_UNFREEZE: cancel the DP_FREEZE command group The slave groups to be addressed, where bit 0 means
group 1, bit 1 means group 2 etc. The bits can be logically ORed. At least one bit must be set.
error Address of a structure provided by the DP user program of the type DP_ERROR_T. If an error occurred, the structure contains details for troubleshooting (see Section 4.4).
Return Value
Name Description
DP_OK Successful completion of function
DP_ERROR_EVENT_NET and error->error_code ==
DP_RET_CP_ADR_NOT_IN_DB
Slave address not in the database.
DP_ERROR_EVENT_NET and error->error_code ==
DP_RET_CP_REQ_NOT_ALLOWE D
The service is not permitted.
DP_ERROR_EVENT_NET and error->error_code ==
DP_RET_CP_SLV_NOT_ACTIV
The relevant slave is not activated.
DP_ERROR_EVENT_NET and error->error_code ==
DP_RET_CP_TOO_MANY_CTRL_C MD
Too many global control commands currently being processed.
DP_ERROR_REQ_PAR and error->error_code ==
DP_RET_CP_WRONG_
FREEZE_GRP
Only with single addressing.
The addressed slave does not belong to any of the specified groups
(command was FREEZE or UNFREEZE).
DP_ERROR_REQ_PAR and error->error_code ==
DP_RET_CP_WRONG_SYNC_GRP
Only with single addressing.
The addressed slave does not belong to any of the specified groups
(command was SYNC or UNSYNC).
DP_ERROR_REQ_PAR and error->error_code ==
DP_RET_CP_WRONG_GC_GRP
At least one of the specified groups is empty.
DP_ERROR_REQ_PAR and error->error_code ==
DP_RET_CP_WRONG_GC_CMD
Illegal global control command.
Others Unsuccessful completion of function
DP Base Programming Interface for CP 5613/CP 5614
C79000-G8976-C139-09 135
4.1.13 DP_ds_read
Purpose
This function sends a "Read Data Record" call to a DP-V1 slave. The DP-V1 data is read parallel to cyclic operation. This is, however, not slave input data but an additional data packet addressed using the slot and index of a slave. The structure and significance of the data varies depending on the slave type and is described in the documentation of the slave.
Note
Reading is executed asynchronously (DP_OK_ASYNC). The result must be fetched with DP_get_result.
Syntax
DPR_DWORD DP_ds_read (DPR_DWORD user_handle, // in
DPC1_REQ_T *request, // in
DP_ERROR_T *error ); // out
Parameters
Name Description
user_handle User handle assigned with the DP_open call.
request Pointer to DP-V1 structure DPC1_REQ_S with entries for the read data record job.
typedef struct DPC1_REQ_S
DP_DS_READ_T dp_ds_read;
DP_DS_WRITE_T dp_ds_write;
DP_ALARM_ACK_T dp_alarm_ack;
DP_ENABLE_EVT_T dp_enable_evt;
DP_GET_CFG_T dp_get_cfg;
}req;
Table continued on next page
DP Base Programming Interface for CP 5613/CP 5614
C79000-G8976-C139-09 137
Continued
Name Description
"Request"
continued The order_id is a job identifier assigned by the DP user program. The identifier is returned unchanged in the asynchronous confirmation and can be used to identify the job to which the confirmation belongs.
The c_ref element specifies the slave. The value of c_ref can be obtained using the function DP_get_cref(user_id, slv_add).
For information on the elements slot_number and index, please refer to the slave description.
The length_s element specifies the length of the data to be read. After receiving the DP_ds_read confirmation,
length_s contains the actual number of data received from the slave. The received data is entered in data_s.
error Address of a structure provided by the DP user program of the type DP_ERROR_T. If an error occurred, the structure contains details for troubleshooting (see Section 4.4).
Return Value
Name Description
DP_OK_ASYNC Execution of the function was activated successfully.
DP_ERROR_EVENT_NET and error->error_code ==
DP_RET_REQ_ACTIV
There is still a DP_ds_read or DP_ds_write request active. Calling DP_ds_read again, is only permitted when the result of the previous call has been fetched with DP_get_result.
other Unsuccessful completion of function
4.1.14 DP_ds_write
Purpose
With this function, the master can send data to a slave. The data is sent parallel to cyclic operation.
This is, however, not slave output data but an additional data packet addressed using the slot and index of a slave. The structure and significance of the data varies depending on the slave type and is described in the documentation of the slave.
Note
Writing is executed asynchronously. The result must be fetched with DP_get_result.
Syntax
DPR_DWORD DP_ds_write ( DPR_DWORD user_handle, // in
DPC1_REQ_T *request // in
DP_ERROR_T *error ); // out
DP Base Programming Interface for CP 5613/CP 5614
C79000-G8976-C139-09 139
Parameters
Name Description
user_handle User handle assigned with the DP_open call.
request Pointer to DP-V1 structure DPC1_REQ_S with entries for the write data record job.
typedef struct DPC1_REQ_S
DP_DS_READ_T dp_ds_read;
DP_DS_WRITE_T dp_ds_write;
DP_ALARM_ACK_T dp_alarm_ack;
DP_ENABLE_EVT_T dp_enable_evt;
DP_GET_CFG_T dp_get_cfg;
}req;
DPR_BYTE data_m[DPR_DPC1_MAX_LENGTH];
// in
} DP_DS_WRITE_T;
The order_id is a job identifier assigned by the DP user program. The identifier is returned unchanged in the asynchronous confirmation and can be used to identify the job to which the confirmation belongs.
The c_ref element specifies the slave. The value of c_ref can be obtained using the function DP_get_cref(user_id, slv_add).
For information on the elements slot_number and index, please refer to the slave description.
The length_m element specifies the length of the data to be sent to the slave in data_m.
error Address of a structure provided by the DP user program of the type DP_ERROR_T. If an error occurred, the structure contains details for troubleshooting (see Section 4.4).
Return Value
Name Description
DP_OK_ASYNC Execution of the function was activated successfully.
DP_ERROR_EVENT_NET and error->error_code ==
DP_RET_REQ_ACTIV
There is still a DP_ds_write or DP_ds_read request active. Calling DP_ds_write again, is only permitted when the result of the previous call has been fetched with DP_get_result.
other Unsuccessful completion of function
DP Base Programming Interface for CP 5613/CP 5614
C79000-G8976-C139-09 141