FC_SemaphoreMeTake

FC_SemaphoreMeTake - General Information

Overview

Type:	Function
Available as of:	V1.0.7.0
Versions:	Current version

Task

Reserving a Semaphore.

Description

The function executes the Take() operation on the specified semaphore.

The following actions depend on the state of the semaphore.

oIf the semaphore is full, it switches to the empty state and the call-up task continues execution; the task then owns the semaphore.

oIf the semaphore is empty and i_xNoTimeOut = FALSE, the call-up task is blocked. It then waits for the owner of the semaphore to execute the Give() operation. If the Give() operation is not executed due to a detected programming error, the blocked task transmits a detected exception error after a long time out. A diagnostic message is entered in the system logger.

oIf the semaphore is empty and i_xNoTimeOut = TRUE, the call-up task is not blocked. The function only reports that the semaphore is empty. The function call-up can be executed again later to retry the reservation of the semaphore.

Any number of tasks can wait simultaneously for a semaphore.

For restrictions for use see Notes on Using the "SemaphoreMutualExclusion" Function.

Interface

Input	Data type	Description
i_xNoTimeout	BOOL	FALSE: the semaphore is reserved, depending on its state, or an error is transmitted. TRUE: the Task is stopped until the semaphore is released or the time out elapsed.

Input

Data type

Description

i_xNoTimeout

BOOL

FALSE: the semaphore is reserved, depending on its state, or an error is transmitted.

TRUE: the Task is stopped until the semaphore is released or the time out elapsed.

Output	Data type	Description
q_etDiag	GD.ET_Diag	General library-independent statement on the diagnostic. A value not equal to ET_Diag.Ok corresponds to an diagnostic message.
q_etDiagExt	ET_DiagExt	POU-specific output on the diagnostic. q_etDiag = ET_Diag.Ok -> Status message q_etDiag <> ET_Diag.Ok -> Diagnostic message

Output

Data type

Description

q_etDiag

GD.ET_Diag

General library-independent statement on the diagnostic.

A value not equal to ET_Diag.Ok corresponds to an diagnostic message.

q_etDiagExt

ET_DiagExt

POU-specific output on the diagnostic.

q_etDiag = ET_Diag.Ok -> Status message

q_etDiag <> ET_Diag.Ok -> Diagnostic message

Input/Output	Data type	Description
iq_stSemMe	ST_SemaphoreMe	Structure of the semaphore to be reserved

Return Value

Data type	Description
BOOL	TRUE: the semaphore has been successfully reserved. FALSE: the semaphore has not been reserved.

Diagnostic Messages

q_etDiag	q_etDiagExt	Enumeration value	Description
OK	Ok	0	Ok
InputParameterInvalid	SemaphoreMeNotInitialized	266	SemaphoreMe is not initializd.
UnexpectedProgramBehavior	SemaphoreMeTakeFailed	273	Requesting the SemaphoreMe was unsuccessful.
UnexpectedProgramBehavior	SemaphoreMeTakeTimeout	269	Timeout when requesting the SemaphoreMe

Enumeration name:	Ok
Enumeration value:	0
Description:	Ok

The semaphore has been successfully reserved.

SemaphoreMeNotInitialized

Enumeration name:	SemaphoreMeNotInitialized
Enumeration value:	266
Description:	SemaphoreMe is not initializd.

Issue	Cause	Solution
-	The semaphore is not initialized.	Transfer the same semaphore which was used during call-up of FC_SemaphoreMeCreate at the iq_stSemMe input.

SemaphoreMeTakeFailed

Enumeration name:	SemaphoreMeTakeFailed
Enumeration value:	273
Description:	Requesting the SemaphoreMe was unsuccessful.

Issue	Cause	Solution
-	An error occurred in the internal execution.	Please inform the support team about this error.

SemaphoreMeTakeTimeout

Enumeration name:	SemaphoreMeTakeTimeout
Enumeration value:	269
Description:	Timeout when requesting the SemaphoreMe

Issue	Cause	Solution
-	The semaphore has not been released during time out.	Ensure that the semaphore has been released with FC_SemaphoreMeGive and has not been reserved again with FC_SemaphoreMeTake. Set the i_xNoTimeout input to TRUE to request the state of the semaphore and, if it is used, retry in the next program cycle.
-	An error occurred in the internal execution.	Please inform the support team about this error.

Issue

Cause

Solution

The semaphore has not been released during time out.

Ensure that the semaphore has been released with FC_SemaphoreMeGive and has not been reserved again with FC_SemaphoreMeTake.

Set the i_xNoTimeout input to TRUE to request the state of the semaphore and, if it is used, retry in the next program cycle.

An error occurred in the internal execution.

Please inform the support team about this error.