Using Logical @Functions

A large number of @Functions can be classified as logical @Functions. These functions return a Boolean result. Remember that in the Formula language, True is represented as 1 and False is represented as . The return values of these logical @Functions reflect this numeric equivalent of true and false . Table 12.5 lists logical @Functions.

Table 12.5. Logical @Functions

@Function	Description
@IsAgentEnabled	Returns True if the agent is enabled.
@IsAppInstalled	Tests whether Admin or Design client is installed.
@IsAvailable	Tests whether a field exists in a document.
@IsCategory	Returns True if any item in a row of a view is a category.
@IsDocBeingEdited	Returns True if the document is in edit mode.
@IsDocBeingLoaded	Returns True if the document is being opened (loaded).
@IsDocBeingMailed	Returns True if the document is being mailed.
@IsDocBeingRecalculated	Returns True if the documents is being refreshed (recalculated).
@IsDocBeingSaved	Returns True if the document is being saved.
@IsDocTruncated	Returns True if the document is truncated.
@IsError	Returns True if a value has an error condition.
@IsExpandable	Returns True if a row in a view is expandable.
@IsMember	Returns True if a text item or text list is a member of another text list.
@IsModalHelp	Returns True if the document is a modal help document.
@IsNewDoc	Returns True if the document has just been created.
@IsNotMember	Returns True if a text item or text list is not a member of another text list.
@IsNull	Returns True if the value is a single text value that contains nothing; otherwise , returns false .
@IsNumber	Returns True if the value is numeric.
@IsResponseDoc	Returns True if the document is a response document.
@IsText	Returns True if the value is text.
@IsTime	Returns True if the value is a time-date value or a time-date list.
@IsUnavailable	Returns True if the field does not exist in the document.
@IsValid	Returns True if all validation formulas are successful.
@IsVirtualizedDirectory	If virtualized directories are enabled on the current server, returns True .
@False	Returns False , or .
@No	Returns False , or .
@True	Returns True , or 1 .
@Yes	Returns True , or 1 .
@Success	Returns True , or 1 .

The Boolean or logical @Functions in Table 12.5 can be used in many different places. Many of these @Functions are related to the state of a document, such as @IsDocBeingEdited or @IsNewDoc . You can use @Functions such as these to hide actions or to determine whether to populate a field. For example, placing @IsNewDoc in the Hide When of an action button will hide it when a document is first created. Similarly, if you have a computed for display field that depends on the value of another field in the document, you can populate the value of the display field using @IsNewDoc :

@If(@IsNewDoc; "New Service Request"; cStatus)

The @Functions @IsAvailable and @IsUnavailable are used to determine whether a field exists in a document. Remember that you can add and delete fields from documents, so you can't always predict whether a given document will have a specific field. Instead of having a formula return an error condition because the field doesn't exist, you can test for its existence before executing the formula. Otherwise, the error condition reported by Notes is assigned to the field, variable, or view column. For example, you might want to sort and categorize a view on a date field that exists in some, but not all, documents. If the field containing the date doesn't exist, you want to sort it on the date of the document's creation. The following formula tests whether the date field exists and uses it if it does; otherwise, it uses @Created .

jdDate := @If(@IsAvailable(dCall) 
 & dCall != ""; dCall; @Created);
@Date(jdDate)

Several other useful @Functions are worth mentioning briefly . Fields and values can have an error condition if the statement that assigns the value produces an error. Using @IsError or @IfError , you can trap for the error condition and assign a different value. The @Functions @IsText , @IsNumber , and @IsTime test the data type of a field. @IsMember and @IsNotMember are used with lists to determine whether a value or list exists within another list.

You might have noticed that @Failure is not in Table 12.5, even though it would seem to be the opposite of @Success . In fact, it is often used in conjunction with @Success . @Success has a return value of 1 , but @Failure returns a string value in a dialog box. For example, if you want to alert the user that a value entered in a field is incorrect or that a field with a required entry was left blank, you can use @Failure in a field's Input Validation event, as in the following example:

@If(cSubject = ""; 
 @Failure("You must enter a subject in order to save this document!");
@Success)

The previous formula produces a window containing the text inside the quotes, alerting the user that the document cannot be saved until an appropriate value is entered in the subject field.