C Language Library Reference

This chapter describes reference information for the C language library you can use in Siebel eScript. It includes the following topics:

Overview of the Clib Object

The Clib (C library) object includes functions that are part of the standard library of the C programming language. It includes methods that can reference files, directories, strings, the environment, memory, and characters. It also includes time functions, error functions, sorting functions, and math functions. Siebel CRM supports the Clib library in Windows servers and Unix servers. It does not support the Clib library for Browser script.

The Clib object is a wrapper you can use to call a function in the standard C library as implemented for a specific operating system. The methods that this chapter describes might behave differently on different operating systems.

Using Siebel eScript Methods Instead of Clib Methods

The following table lists each Clib method that has an equivalent method in Siebel eScript. These methods are redundant because their functionality already exists in Siebel eScript. Where possible, you must use the Siebel eScript method instead of the equivalent Clib method. In some situations the Clib method is preferred and is more consistent in a section of script. For example, when working with a string routine that expects a null string.

Siebel eScript Method	Clib Method	Description
Get Absolute Value Method	abs	Calculates absolute value.
Get Arc Cosine Method	acos	Calculates the arc cosine.
Get Arcsine Method	asin	Calculates the arc sine.
Get Arctangent Method	atan	Calculates the arc tangent.
Get Arctangent 2 Method	atan2	Calculates the arc tangent of a fraction.
Convert String to Floating-Point Number Method	atof	Converts a string to a floating-point number.
Convert String to Integer Method	atoi	Converts a string to an integer.
Automatic conversion	atol	Converts a string to a long integer.
Get Ceiling Method	ceil	Rounds a number up to the nearest integer.
Get Cosine Method	cos	Calculates the cosine.
Get Exponential Method	exp	Calculates the exponential function.
Math absolute	fabs	Calculates the absolute value of a floating-point number.
Get Floor Method	floor	Rounds a number down to the nearest integer.
% operator, modulo	fmod	Calculates the remainder.
Math absolute	labs	Returns the absolute value of a long.
Get Logarithm Method	log	Calculates the natural logarithm.
Get Maximum Method	max	Returns the largest of one or more values.
Get Minimum Method	min	Returns the smallest of one or more values.
Raise Power Method	pow	Calculates x to the power of y.
Get Sine Method	sin	Calculates the sine.
Get Square Root Method	sqrt	Calculates the square root.
+ operator	strcat	Appends one string to another.
== operator	strcmp	Compares two strings.
= operator	strcpy	Copies a string.
Get String Length Method	strlen	Gets the length of a string.
Change String to Lowercase Method	strlwr	Converts a string to lowercase.
Automatic conversion	strtod	Converts a string to decimal.
Automatic conversion	strtol	Converts a string to long.
Change String to Uppercase Method	strupr	Converts a string to uppercase.
Get Tangent Method	tan	Calculates the tangent.
string.toLowerCase	tolower	Converts a character to lowercase.
string.toUpperCase	toupper	Converts a character to uppercase.

The phrase automatic conversion in the Siebel eScript Method column means that Siebel eScript implicitly performs a conversion. For example, when comparing Siebel eScript to the atol Clib method, if the variable that will hold the converted string is of type Number, then Siebel eScript implicitly converts the string from a string to a long integer.

Clib File and Directory Methods

This topic describes Clib methods to create, open, lock, close, and delete files. It also describes methods to manipulate directories. It includes the following topics:

Overview of Clib File and Directory Methods

Siebel eScript can interpret a backslash (\) as a character combination. If you create a Windows path name, then you must include two backslashes to prevent this interpretation. For example:

To change the working directory to C:\Applications\Myfolder, you use the following command:
```
Clib.chdir(“C:\\Applications\\Myfolder”);
```
To use a UNC path to access a computer on your network, use four backslashes (\\\\) before the computer name:
```
Clib.system("copy \\\\server01\\share\\SR.txt D:\\SR.txt ");
```

For general usage information that applies to these methods, see Overview of Clib File Input and Output Methods.

Clib Close File Method

The Clib Close File method writes to disk the data that currently resides in the buffer for a file. It then closes this file. It returns one of the following values:

If successful, then it returns the following value:
Zero
If not successful, then it returns the following value:
EOF

The file pointer is no longer valid after this call.

Format

Clib.fclose(filePointer)

The arguments for this method are the same as the arguments for the Clib Clear Error method. For more information, see Clib Clear Error Method.

Example

The following example creates and writes to a text file, and then closes this file. It also tests for an error condition. If an error occurs, then it displays a message and clears the buffer:

function Test_Click ()

{

   var fp = Clib.fopen('c:\\temp000.txt', 'wt');

   Clib.fputs('abcdefg\nABCDEFG\n', fp);

   if (Clib.fclose(fp) != 0)

   {

      TheApplication().RaiseErrorText('Unable to close file.' + 

         '\nContents are lost.');

   }

   else

      Clib.remove('c:\\temp000.txt');

}

For more information, see Clib Clear Buffer Method.

Clib Create Temporary File Method

The Clib Create Temporary File method creates and opens a temporary binary file. It automatically removes the file pointer and the temporary file when Siebel CRM closes the file or when the code finishes. It returns one of the following values:

If successful, then it returns the file pointer of the file that it created.
If not successful, then it returns the following value:
Null

The location of where it creates the temporary file depends on how Clib is implemented on the operating system you use.

Format

Clib.tmpfile()

For an example, see Clib Get Characters to Next Line Method.

Clib Create Temporary File Name Method

The Clib Create Temporary File Name method creates a temporary file name. This name is not the same as the name of any existing file and it is not the same as any file name that this method returns while this code runs. It returns the file name as a string in the str argument.

Format

Clib.tmpnam([str])

The following table describes the arguments for the Clib Create Temporary File Name method.

Argument	Description
str	A container that holds the name of the temporary file.

Clib Delete File Method

The Clib Delete File method deletes a file. It returns one of the following values:

If successful, then it returns the following value:
0
If not successful, then it returns the following value:
Negative 1

Format

Clib.remove(filename)

The following table describes the arguments for the Clib Delete File method.

Argument	Description
filename	A string or string variable that contains the name of the file that this method deletes.

Clib Lock File Method

The Clib Lock File method locks or unlocks a file for simultaneous use by multiple processes. It returns one of the following values:

If successful, then it returns the following value:
0
If not successful, then it returns a nonzero integer.

Format

Clib.flock(filePointer, mode)

The following table describes the arguments for the Clib Lock File method.

Argument	Description
filePointer	The file that this method locks or unlocks. The Clib Open File method or the Clib Create Temporary File method can return this file name.
mode	You can specify one of the following values: LOCK_EX. Lock for exclusive use. LOCK_SH. Lock for shared use. LOCK_UN. Unlock. LOCK_NB. Nonblock.

Argument

Description

filePointer

The file that this method locks or unlocks. The Clib Open File method or the Clib Create Temporary File method can return this file name.

mode

You can specify one of the following values:

LOCK_EX. Lock for exclusive use.
LOCK_SH. Lock for shared use.
LOCK_UN. Unlock.
LOCK_NB. Nonblock.

Usage

The Clib Lock File method applies or removes an advisory lock on the file that the filePointer argument identifies. An advisory lock is a type of lock that allows cooperating processes to perform consistent operations on a file. Other processes might still reference the files, so inconsistencies might occur.

Locking allows the following types of locks:

Shared lock. Multiple processes can use shared locks on the same file at the same time. Read permission is required to obtain a shared lock.
Exclusive lock. The following configurations cannot exist on one file at the same time:
- Multiple exclusive locks
- Shared locks and an exclusive lock
Write permission is required to obtain an exclusive lock.

If you use the Clib Lock File method to:

Lock a file that a calling process already locked, then it removes the old lock type and replaces it with the new lock type. The Lock method locks individual files and not segments.
Lock a file that is already locked and:
- You do not specify LOCK_NB in the mode argument, then it pauses the lock request until the file is free.
- Specify LOCK_NB in the mode argument, then the call fails and this method returns an EWOULDBLOCK error.

Siebel eScript does not support the Clib Lock File method in a Unicode environment. It always returns 0 in a Unicode environment.

Clib Open File Method

The Clib Open File method opens the file that you specify in the filename argument. It opens it in the mode that you specify in the mode argument. It returns one of the following values:

If successful, then it returns a file pointer to the file that it opened.
If not successful, then it returns the following value:
Null

If this method successfully opens a file, then it clears the error status for this file and initializes a buffer for automatic buffering of read and write activity with the file.

Several Clib methods require an argument named filePointer. It is often the return value of a Clib Open File call.

Format

Clib.fopen(filename, mode)

The following table describes the arguments for the Clib Open File method.

Argument	Description
filename	Any valid file name that does not include a wildcard character.
mode	One of the required characters that specify a file mode followed by optional characters. For more information, see Clib Open File Method.

Usage for the Mode Argument

The following table describes usage for the mode argument. The mode argument is a string that includes one of the following required characters, and then followed by other optional characters:

r
w
a

Argument	Mode	Required
r	Opens the file for reading. The file must already exist.	Yes. You must include one of these arguments.
w	Opens the file for writing. If the file does not exist, then Siebel eScript creates the file.
a	Opens the file in append mode.
b	Opens the file in binary mode. If you do not specify b, then this method opens the file in text mode and performs an end-of-line translation.	No
t	Opens the file in text mode. For a non-ASCII character: You use the u argument. You do not use the t argument.	No
u	Opens the file in Unicode mode as UTF-16 or Little Endian. For example: Clib.fopen(“filename.txt”, “rwu”) You can use the u mode for ASCII and non-ASCII characters.	No
+	Opens the file for reading and writing.	No

Example 1

The following example opens the ReadMe text file for text mode reading and displays each line in that file:

var fp:File = Clib.fopen("ReadMe","rt");

if ( fp == null ) 

   TheApplication().RaiseErrorText("\aError opening file for reading.\n")

else 

{

   while ( null != (line=Clib.fgets(fp)) )

   {

      Clib.fputs(line, stdout)

   }

}

Clib.fclose(fp);

The following example opens a file, writes a string to that file, and then uses the default codepage to read the string from this file:

var oFile = Clib.fopen("myfile","rw");

if (null != oFile)

{

   var sHello = "Hello";

   var nLen = sHello.length;

   Clib.fputs(sHello, oFile);

   Clib.rewind(oFile);

   Clib.fgets (nLen, sHello);

}

The following example opens a file, writes a string to this file, then uses Unicode to read the string from this file:

var oFile = Clib.fopen("myfile","rwu");

if (null != oFile)

{

   var sHello = "Hello";

   var nLen = sHello.length;

   Clib.fputs(sHello, oFile);

   Clib.rewind(oFile);

   Clib.fgets (nLen, sHello);

}

The following example specifies a file path:

function WebApplet_ShowControl (ControlName, Property, Mode, &HTML)

{

if (ControlName == "GotoUrl")

   {

      var fp = Clib.fopen("c:\\test.txt","wt+");

      Clib.fputs("property = " + Property + "\n", fp);

      Clib.fputs("mode = " + Mode + "\n",fp);

      Clib.fputs("ORG HTML = " + HTML + "\n",fp);

      Clib.fclose(fp);

      HTML = "<td>New HTML code</td>";

   }

return(ContinueOperation);

For more information, see the following topics:

Clib Rename File Method

The Clib Rename File method renames a file. It returns one of the following values:

If successful, then it returns the following value:
0
If not successful, then it returns the following value:
Negative 1

Format

Clib.rename(oldName, newName)

The following table describes the arguments for the Clib Rename File method.

Argument	Description
oldName	A string that contains the name of the file that this method renames. This name can be an absolute file name or a relative file name.
newName	A string that contains the new file name.

Clib Reopen File Method

The Clib Reopen File method closes the file associated with a file pointer. It then opens a file and associates it with the file pointer of the file that it closed. You can use it to redirect one of the predefined file handles to a file or from a file. These file handles include stdout, stderr, and stdin. It returns one of the following values:

If successful, then it returns a copy of the old file pointer.
If not successful, then it returns the following value:
Null

Format

Clib.freopen(filename, mode, oldFilePointer)

The following table describes the arguments for the Clib Reopen File method.

Argument	Description
filename	The name of the file that this method opens.
mode	One of the file modes specified in Clib Open File method. For Unicode, you can use the same u flag that you can use in the Clib Open File method.
oldFilePointer	The file pointer to the file that the Clib Reopen File method closes and where it associates the file that you specify in the filename argument.

Example

The following example uses the same file pointer to write to two different files:

var oFile = Clib.fopen("c:\\temp\\firstfile","w");

if (oFile == null)

{

   TheApplication().RaiseErrorText("File not found.");

}

Clib.fprintf(oFile, "Writing to first file\n");

Clib.freopen("c:\\temp\\secondfile", "w", oFile);

if (oFile == null)

{

   TheApplication().RaiseErrorText("File not found.");

}

Clib.fprintf(oFile, "Writing to second file\n");

Clib.fclose(oFile);

For more information, see the following topics:

Clib Change Directory Method

The Clib Change Directory method modifies the current directory for the Siebel application. It returns one of the following values:

If successful, then it returns the following value:
0
If not successful, then it returns the following value:
Negative 1

If you restart the Siebel Server, then Siebel CRM automatically resets the current directory depending on one of the following operating systems that you use:

Windows. The current directory on the Siebel Server that the Windows operating system recognizes.
UNIX. The home directory of the administrator who restarts the Siebel Server.

Format

Clib.chdir(dirPath)

The following table describes the arguments for the Clib Change Directory method.

Argument	Description
dirpath	The directory path that this method makes current. This path can be absolute or relative.

Example

The following example uses the Clib Change Directory method to change the current working directory of the Siebel application. The default Siebel working directory is SIEBEL_ROOT\bin. For example, if you install the Siebel client in the C:\sea81\client directory, then the default working directory is C:\sea81\client\bin:

function Application_Start (CommandLine)

{

  

   // Start Tracing 

   TheApplication().TraceOn("c:\\temp\\SiebTrace.txt","Allocation","All");



   var currDir = Clib.getcwd();

   TheApplication().Trace("Current directory is " + Clib.getcwd());



   // Create a new directory  

   var msg = Clib.mkdir('C:\\Clib test');



   // Display the error flag created by creating directory;   

   // Must be 0, indicating no error.



   TheApplication().Trace(msg);



   // Change the current directory to the new 'Clib test'

   Clib.chdir("C:\\Clib test");

   TheApplication().Trace("Current directory is " + Clib.getcwd());



   // Delete 'Clib test'

   Clib.chdir("C:\\");



   // Attempting to make a removed directory current gives an 

   // error

   Clib.rmdir("Clib test");

   msg = Clib.chdir("C:\\Clib test");

   TheApplication().Trace(msg);

}

This example produces the following result:

Current directory is D:\sea81\client\BIN

0

Current directory is C:\Clib test

-1

Clib Create Directory Method

The Clib Create Directory method creates a directory. It returns one of the following values:

If successful, then it returns the following value:
0
If not successful, then it returns the following value:
negative 1

Format

Clib.mkdir(dirpath)

The following table describes the arguments for the Clib Create Directory method.

Argument Description

Argument	Description
dirpath	A string that contains a valid directory path. This directory can be an absolute path or a relative path. This method uses this string to create the directory. If you do not specify the dirpath argument, then it creates the directory in the `C:\siebel\bin` directory.

dirpath

A string that contains a valid directory path. This directory can be an absolute path or a relative path.

This method uses this string to create the directory. If you do not specify the dirpath argument, then it creates the directory in the C:\siebel\bin directory.

Clib Get Current Working Directory Method

The Clib Get Current Working Directory method returns the entire path of the current working directory. The default current working directory is the directory where you install the Siebel application.

If a script uses the Clib Change Directory method or a similar method to change the current working directory, then the current working directory returns to the original value after the script finishes.

Format

Clib.getcwd()

The following example displays the current directory in a message box. The script then makes the root directory the current directory, creates a new directory, removes that directory, and then attempts to make the removed directory current:

function Button_Click ()
{
   var currDir = Clib.getcwd();

   TheApplication().Trace("Current directory is " + Clib.getcwd());

   var msg = Clib.mkdir('C:\\Clib test');

   // Display the error flag created by creating directory;   

   // Must be 0, indicating no error.

   TheApplication().Trace(msg);

   // Change the current directory to the new 'Clib test'

   Clib.chdir("C:\\Clib test");

   TheApplication().Trace("Current directory is " + Clib.getcwd());

   // Delete 'Clib test'

   Clib.chdir("C:\\");

   // Attempting to make a removed directory current yields error

       flag

   Clib.rmdir("Clib test");

   msg = Clib.chdir("C:\\Clib.test");

   TheApplication().Trace(msg);

}

This example displays the following output:

Current directory is C:\SIEBEL\BIN

0

Current directory is C:\Clib test

-1

Clib Remove Directory Method

The Clib Remove Directory method removes a directory. It returns one of the following values:

If successful, then it returns the following value:
0
If not successful, then it returns the following value:
Negative 1

Format

Clib.rmdir(dirpath)

The following table describes the arguments for the Clib Remove Directory method.

Argument	Description
dirpath	The directory that this method removes. This argument can reference an absolute path or a relative path.

Clib File Input and Output Methods

This topic describes Clib file input and output methods. It includes the following topics:

Overview of Clib File Input and Output Methods

Siebel eScript handles file input and file output operations in a way that is similar to the C programming language and the C++ programming language. These languages do not directly read to or write from files. With Siebel eScript, you must first configure the language to open a file. To do this, you typically pass the name of this file to the Clib Open File method.

File input and file output methods in Siebel eScript read the file into a buffer in memory and return a file pointer, which is a pointer that references the beginning of the buffer. The file stream is the data that the buffer contains. Reading and writing occurs relative to the buffer, which is not written to disk unless you explicitly use the Clib Clear Buffer method to clear the buffer or use the Clib Close File method to close the file.

Format Characters for Methods That Print and Scan

A method that prints or scans uses a format string to format the data that the method reads and writes.

Format Characters for Methods That Print

This topic describes format characters for methods that print. The following methods can perform print operations:

Each of these methods prints each character while it reads the input until the method encounters a percentage symbol (%). This symbol instructs that method to use the following format to print a value:

%[flags][width][.precision]type

To include the % symbol as a character in the string, you use two consecutive percentage symbols (%%).

Characters That Format Values

The following table describes characters that format a value.

Character	Description	Example Statement and Output
-	Left justification in the field with space padding or right justification with zero or space padding.	`fprintf(file, "[%-8i]", 26);` `[26 ]`
+	Force numbers to begin with a plus symbol (+) or a minus symbol (-).	`fprintf(file, "%+i", 26);` `+26`
space	A negative value that begins with a minus symbol (-). A positive value begins with a space.	`fprintf(file, "[% i]", 26);` `[ 26]`
#	Append one of the following symbols to the pound (#) character to display the output in one of the following forms: o. Prefix a zero to nonzero octal output. x or X. Prefix 0x or 0X to the output, which indicates hexadecimal. f. Include a decimal point even if no digits follow the decimal point. e or E. Include a decimal point even if no digits follow the decimal point, and display the output in scientific notation. g or G. Include a decimal point even if no digits follow the decimal point, display the output in scientific notation, depending on precision, and leave trailing zeros in place.	`fprintf(file, "%#o", 26);` `032` `fprintf(file, "%#x", 26);` `0x1A` `fprintf(file, "%#.f", 26);` `26.` `fprintf(file, "%#e", 26);` `2.600000e+001` `fprintf(file, "%#g", 26);` `26.0000`
f	Floating-point of the format [-]dddd.dddd.	`fprintf(file, "%f", 26.735);` `26.735000`
e	Floating-point of the format [-]d.ddde+dd or [-]d.ddde-dd.	`fprintf(file, "%e", 26.735);` `2.673500e+001`
E	Floating-point of the format [-]d.dddE+dd or [-]d.dddE-dd.	`fprintf(file, "%E", 26.735);` `2.673500E+001`
g	Floating-point number of f or e type, depending on precision.	`fprintf(file, "%g", 26.735);` `26.735`
G	Floating-point number of F or E type, depending on precision.	`fprintf(file, "%G", 26.735);` `26.735`
c	Character. For example, a, b, or 8.	`fprintf(file, "%c", 'a');` `a`
s	String.	`fprintf(file, "%s", "Test");` `Test`

Characters That Determine Width

The following table describes characters that determine width.

Character Description Example Statement and Output

Character	Description	Example Statement and Output
n	At least n characters are output. If the value is less than n characters, then Siebel eScript pads that precedes the output with spaces.	`fprintf(file, "[%8s]", "Test");` `[ Test]`
0n	At least n characters are output pads that precedes the output with zeros.	`fprintf(file, "%08i", 26);` `00000026`
*	The next value in the argument list is an integer that specifies the output width.	`fprintf(file, "[%*s]", 8, "Test");` `[ Test]`

n

At least n characters are output. If the value is less than n characters, then Siebel eScript pads that precedes the output with spaces.

fprintf(file, "[%8s]", "Test");

[ Test]

0n

At least n characters are output pads that precedes the output with zeros.

fprintf(file, "%08i", 26);

00000026

*

The next value in the argument list is an integer that specifies the output width.

fprintf(file, "[%*s]", 8, "Test");

[ Test]

Characters That Determine Precision

The following table describes characters that determine precision. If you specify precision, then you must begin the precision format with a period (.) and you must use one of the forms described in Format Characters for Methods That Print.

Character Description Example Statement and Output

Character	Description	Example Statement and Output
.0	For floating-point type. No decimal point is output.	`fprintf(file, "%.0f", 26.735);` `26`
.n	Output is n characters. If the value is a floating-point number, then the output is n decimal places. Assume you specify a Width value and a .n Precision value when you format a floating point number. In this situation, to determine the width of the output and to determine if it must pad the output, the method counts the decimal point and the characters that occur before and after the decimal point. For example: fprintf(file, "%10.2f", 26.735); [ 26.73]	`fprintf(file, "%.2f", 26.735);` `26.73`
.*	The next value in the argument list is an integer that specifies the precision width.	`fprintf(file, "%.*f", 1, 26.735);` `26.7`

.0

For floating-point type. No decimal point is output.

fprintf(file, "%.0f", 26.735);

26

.n

Output is n characters. If the value is a floating-point number, then the output is n decimal places.

Assume you specify a Width value and a .n Precision value when you format a floating point number. In this situation, to determine the width of the output and to determine if it must pad the output, the method counts the decimal point and the characters that occur before and after the decimal point. For example:

fprintf(file, "%10.2f", 26.735);

[     26.73]

fprintf(file, "%.2f", 26.735);

26.73

.*

The next value in the argument list is an integer that specifies the precision width.

fprintf(file, "%.*f", 1, 26.735);

26.7

Characters That Determine Character Type

The following table describes characters that determine character type.

Character	Description	Example Statement and Output
d,i	Signed integer.	`fprintf(file, "%i", 26);` `26`
u	Unsigned integer.	`fprintf(file, "%u", -1);` `4294967295`
o	Octal integer.	`fprintf(file, "%o", 26);` `32`
x	Hexadecimal integer using 0 through 9 and a, b, c, d, e, or f.	`fprintf(file, "%x", 26);` `1a`
X	Hexadecimal integer using 0 through 9 and A, B, C, D, E, or F.	`fprintf(file, "%X", 26);` `1A`
f	Floating-point of the format [-]dddd.dddd.	`fprintf(file, "%f", 26.735);` `26.735000`
e	Floating-point of the format [-]d.ddde+dd or [-]d.ddde-dd.	`fprintf(file, "%e", 26.735);` `2.673500e+001`
E	Floating-point of the format [-]d.dddE+dd or [-]d.dddE-dd.	`fprintf(file, "%E", 26.735);` `2.673500E+001`
g	Floating-point number of f or e, depending on precision.	`fprintf(file, "%g", 26.735);` `26.735`
G	Floating-point number of F or E, depending on precision.	`fprintf(file, "%G", 26.735);` `26.735`
c	Character. For example, a, b, 8.	`fprintf(file, "%c", 'a');` `a`
s	String.	`fprintf(file, "%s", "Test");` `Test`

Format Characters for Methods That Scan

This topic describes format characters for methods that scan. The following methods can perform a scan operation:

Note the following:

The format string includes character combinations that specify the type of data.
The format string specifies input sequences and how the method must convert the input.
The method maps each character to the input as it reads the input until it encounters a percentage symbol (%).
The percentage symbol causes the method to read the value, and then store it in an argument that follows the format string.
Each argument that occurs after the format string receives the next parsed value from the next argument in the list of arguments that occur after the format string.

Arguments In a Method That Performs a Scan Operation

An argument in a method that performs a scan operation uses the following format:

%[*][width]type

The following table describes usage of the * (asterisk) and the width argument. If you specify the width, then the input is an array of characters of the length that you specify.

Argument	Description
*	Suppresses assigning this value to any argument.
width	Sets the maximum number of characters to read. If the method encounters a white-space character or a nonconvertible character, then it stops reading these characters. For more information, see Use White Space to Improve Readability.

The following table describes the values you can use for the type argument.

Type Value	Description
d,D,i,I	Signed integer.
u,U	Unsigned integer.
o,O	Octal integer.
x,X	Hexadecimal integer.
f,e,E,g,G	Floating-point number.
s	String.
[abc]	String that includes the characters in brackets, where A–Z represents the range A to Z.
[^abc]	String that includes the following character in brackets: not

Example

The following example creates a file named myfile.txt and stores a float number and a string. It then rewinds the stream and uses fscanf to read the values:

function WebApplet_Load()

{

   var f;

   var str;

   var pFile = Clib.fopen ("c:\\myfile.txt","w+");

   Clib.fprintf (pFile, "%f %s", 3.1416, "PI");

   Clib.rewind (pFile);

   Clib.fscanf (pFile, "%f", f);

   Clib.fscanf (pFile, "%s", str);

   Clib.fclose (pFile);

   Clib.printf ("I have read: %f and %s \n",f,str);

}

This example produces the following output:

I have read: 3.141600 and PI

Clib Clear Buffer Method

The Clib Clear Buffer method writes to disk the data that exists in the buffer depending on the following value in the filePointer argument:

Is not null. It writes to disk any data that exists in the buffer only for the file that the filePointer argument identifies.
Is null. It writes to disk any data that exists in the buffer for all open files.

This method returns one of the following values:

If successful, then it returns the following value:
0
If not successful, then it returns the following value:
EOF

Format

Clib.fflush(filePointer)

The arguments for this method are the same as the arguments for the Clib Clear Error method. For more information, see Clib Clear Error Method.

Clib End of File Method

The Clib End of File method determines if the file cursor is at the end of the file that the filePointer argument identifies. It returns one of the following values:

If the file cursor is at the end of the file, then it returns the following value:
A nonzero integer
If the file cursor is not at the end of the file, then it returns the following value:
0

Format

Clib.feof(filePointer)

The arguments for this method are the same as the arguments for the Clib Clear Error method. For more information, see Clib Clear Error Method.

Clib Get Character Method

The Clib Get Character method returns one of the following values:

The next character from the buffer of the file that the filePointer argument identifies. It returns this value as a byte converted to an integer.
If a read error occurs or if the cursor is at the end of the file, then it returns the following value and stores the error number in the errno property:
EOF

Format

Clib.getc(filePointer)

Clib.fgetc(filePointer)

The arguments for these methods are the same as the arguments for the Clib Clear Error method. For more information, see Clib Clear Error Method.

In most situations, to avoid an error with macro usage, you must use Clib.fgetc.

Clib Get Characters to Next Line Method

The CLib Get Characters to Next Line method returns one of the following values:

A string that includes the characters that exist in a file from the current position of the file cursor up to and including the next newline character.
If an error occurs or if it reaches the end of the file, then it returns the following value:
Null

Format

Clib.fgets([maxLen,] filePointer)

The following table describes the arguments for the Get Characters to Next Line method.

Argument	Description
maxLen	The maximum length of the string that this method returns if it does not encounter a newline character. If the File Mode is Unicode, then the maxLen argument is the length in Unicode characters. If you do not specify the maxLen argument, then Siebel eScript uses the default limit of 999 characters.
filePointer	A file pointer that the Clib Open File method returns.

Argument

Description

maxLen

The maximum length of the string that this method returns if it does not encounter a newline character.

If the File Mode is Unicode, then the maxLen argument is the length in Unicode characters.

If you do not specify the maxLen argument, then Siebel eScript uses the default limit of 999 characters.

filePointer

A file pointer that the Clib Open File method returns.

Example

The following example writes a string that contains an embedded newline character to a temporary file. To return and display the output, it then reads from the file twice:

function Test_Click ()

{

   var x = Clib.tmpfile();

   Clib.fputs("abcdefg\nABCDEFG\n", x);

   Clib.rewind(x);

   var msg = Clib.fgets(x) + " " + Clib.fgets(x);

   Clib.fclose(x);

   TheApplication().RaiseErrorText(msg);

}

This example produces the following output:

abcdefg

ABCDEFG

If the string that the Get Characters to Next Line method returns includes a non-ASCII character, then you must configure Siebel CRM to open in Unicode the file that the filePointer argument specifies.

Caution: If Siebel CRM opens the file in text mode, then this method treats any non-ASCII character it encounters as an end-of-line character and stops reading the current line. As a result, this method might truncate the string that it returns. If the file does not use an encoding standard that is compatible with Unicode, then you must first configure Siebel CRM to transform it to UTF-8 or UTF-16 with the appropriate byte-order mark (BOM) placed at the beginning of the file. For more information, see Clib Open File Method.

Clib Get Cursor Position Method

The Clib Get Cursor Position method gets the current position of the file cursor in the file that the filePointer argument identifies. It stores this value in the position argument.

Format

Clib.fgetpos(filePointer, position)

The following table describes the arguments for the Get Pointer Position method.

Argument	Description
filePointer	A file pointer that the Clib Open File method returns.
position	The current position of the pointer in the file that the filePointer argument identifies.

Example

The following example restores the cursor position. It does the following work:

Writes two strings to a temporary text file.
To save the position where the second string begins, it uses the Clib Get Cursor Position method.

To set the file cursor to the saved position, it uses the Clib Set Cursor Position method:

function Test_Click ()

{

   var position;

   var fp = Clib.tmpfile();

   Clib.fputs("Melody\n”, fp);

   Clib.fgetpos(fp, position)

   Clib.fputs("Lingers\n", fp);

   Clib.fsetpos(fp, position);

   var msg = Clib.fgets(fp));

   Clib.fclose(fp);

   TheApplication().RaiseErrorText(msg);

}

Clib Get Relative Cursor Position Method

The Clib Get Relative Cursor Position method gets the position of the file cursor of an open file relative to the beginning of the file. It returns one of the following values:

If successful, then it returns the current position of the file cursor.
If not successful, then it returns the following value and stores the error value in the errno property:
Negative 1

The cursor position in a text file might not correspond exactly with the byte offset in the file. A text file is a file that is not opened in binary mode.

Format

Clib.ftell(filePointer)

The arguments for this method are the same as the arguments for the Clib Clear Error method. For more information, see Clib Clear Error Method.

Clib Move Cursor to Beginning of File Method

The Clib Move Cursor to Beginning of File method moves the file cursor to the beginning of a file. This method is identical to the Clib Set Cursor Position method with the mode argument set to SEEK_SET and the offset argument set to 0. The only difference is that the Clib Move Cursor to Beginning of File method also clears the error indicator for the file.

Format

Clib.rewind(filePointer)

The arguments for this method are the same as the arguments for the Clib Clear Error method. For more information, see Clib Clear Error Method.

Usage With a Unicode File

Siebel CRM uses UTF-16 encoding when it writes to a file in Unicode. The first two bytes of the file are always the BOM (Byte Order Mark). If the Clib Move Cursor to Beginning of File method calls a Unicode file, then it references BOM (-257) and not the first valid character. To skip the BOM, you must configure Siebel CRM to call the Clib Get Character Method or the Clib File Get Character Method method at least one time. For more information, see Clib Get Character Method.

Example

For an example, see Clib Get Characters to Next Line Method.

Clib Read From File Method

The Clib Read From File method reads data from an open file that you specify in the filePointer argument. It then stores this data in an argument, buffer, or BLOB that you specify. If this argument, buffer, or BLOB does not exist, then this method creates it. It returns one of the following values:

If successful, then it returns the number of elements it read.
If you specify the destBuffer argument, then it returns the number of bytes read, up to the value you specify in the bytelength argument.
If you specify the varDescription argument, then it returns one of the following values:
- 1 if it reads the data
- 0 if a read error occurs or if it encounters the end of file

Arguments

// Format A
Clib.fread(destBuffer, bytelength, filePointer)

// Format B
Clib.fread(destVar, varDescription, filePointer)

// Format C
Clib.fread(blobVar, blobDescriptor, filePointer)

The following table describes the arguments for the Clib Read From File method.

Argument	Description
destBuffer	The buffer to contain the data that this method reads.
bytelength	The number of bytes that this method reads.
filePointer	A file pointer that the Clib Open File method returns.
destVar	A container to hold the data that this method reads.
varDescription	The format of the data that this method reads. For more information, see Clib Read From File Method.
blobVar	The BLOB where this method writes data.
blobDescriptor	The BLOB descriptor for the value you specify in the blobVar argument.

Format of the Data That the Clib Read From File Method Reads

The following table describes the format of the data that the Clib Read From File method reads. You specify this format in the varDescription argument. If the destVar argument must hold a single datum, then you must set the varDescription argument to one of these formats. If the destVar contains blob data, then you must specify a blobdescriptor argument. A blobdescriptor can also consist of varDescriptions for the individual elements of the blobdescriptor.

Value	Description
UWORD8	Stored as an unsigned byte.
SWORD8	Stored as a signed byte.
UWORD16	Stored as an unsigned, 16-bit integer.
SWORD16	Stored as a signed, 16-bit integer.
UWORD24	Stored as an unsigned, 24-bit integer.
SWORD24	Stored as a signed, 24-bit integer.
UWORD32	Stored as an unsigned, 32-bit integer.
SWORD32	Stored as a signed, 32-bit integer.
FLOAT32	Stored as a floating-point number.
FLOAT64	Stored as a double-precision, floating-point number.

The following code includes example formats:

ClientDef = new blobDescriptor();

ClientDef.Sex = UWORD8;

ClientDef.MaritalStatus = UWORD8; 

ClientDef._Unused1 = UWORD16; 

ClientDef.FirstName = 30; ClientDef.LastName = 40; 

ClientDef.Initial = UWORD8;

The Siebel eScript usage of fread differs from the standard C library usage in that the C library reads an array of numeric values or structures into consecutive bytes in memory. The Clib Read From File method reads data in the byte-order that the current value of the BigEndianMode global variable describes.

Example

The following example reads the following items from the fp file:

Reads the 16-bit i integer
Reads the 32-bit f float
Reads the 10-byte buffer from the buf buffer:

if ( !Clib.fread(i, SWORD16, fp) || !Clib.fread(f, FLOAT32, fp)

|| 10 != Clib.fread(buf, 10, fp) )

   TheApplication().RaiseErrorText("Error reading from file.\n"); 

}

Clib Restore Cursor Position Method

The Restore Cursor Position method sets the current file cursor to a position that you specify. You can use it to restore the file cursor to a position that the Clib Get Cursor Position returns. It returns one of the following values:

If successful, then it returns the following value:
0
If not successful, then it returns nonzero and stores the error value in the errno property.

Format

Clib.fsetpos(filePointer, position)

The following table describes the arguments for the Restore Cursor Position method.

Argument	Description
filePointer	A file pointer that the Clib Open File method returns.
position	The value that the Clib Get method returns.

Example

For an example, see Clib Get Cursor Position Method.

Clib Set Cursor Position Method

The Clib Set Cursor Position method sets the position of the file cursor of an open file. It returns one of the following values:

If successful, then it returns the following value:
0
If not successful, then it returns a nonzero value.

Format

Clib.fseek(filePointer, offset[, mode])

The following table describes the arguments for the Clib Set Cursor Position method.

Argument

Description

filePointer

A file pointer that the Clib Open File method returns.

offset

The number of bytes that the Clib Set Cursor Position method moves the file cursor, starting with the value that you specify in the mode argument.

The cursor position in a text file might not correspond exactly with the byte offset in the file. A text file is a file that is not opened in binary mode.

mode

You can specify one of the following values:

SEEK_CUR. Relative to the current position of the file cursor.
SEEK_END. Relative to the end of the file.
SEEK_SET. Relative to the beginning of the file. If you do not specify the mode argument, then this method uses SEEK_SET.

Clib Scan and Convert File Method

The Clib Scan and Convert File method reads data from a file and stores data items that exist in this file in a series of arguments. It returns one of the following values:

If successful, then it returns the number of input items it converted and stored.
If an input failure occurs before the conversion, then it returns the following value:
EOF

Format

Clib.fscanf(filePointer, formatString, var1, var2, ..., varn)

The following table describes the arguments for the Clib Scan and Convert File method.

Argument	Description
filePointer	A file pointer that the Clib Open File method returns.
formatString	A string that contains format instructions that the Clib Open File method uses to read each data item in the file.
var1, var2, ..., varn	Variables that the Clib Open File method uses to store the values that it formats.

Usage

This method does the following work:

Reads input from the file that the filePointer argument identifies.
Matches characters that exist in the file with characters that the formatString argument specifies until it reaches a percentage symbol (%).
The percentage symbol causes this method to read and store the values in the arguments that occur after the string that the formatString argument identifies.
Parses each match that occurs after the value of the formatString argument.
As it parses each match, it stores the result in a variable argument, such as var1, var2, ..., and varn. If a matching failure occurs, then the number of matches it parses might be fewer than the number of variable arguments you specify.

An argument specification uses the following format:

%[*][width]type

For values for these items, see Format Characters for Methods That Scan.

You must make sure that the file it reads is open and includes read access.

Example

The following example uses the Clib Scan and Convert File method with various options on the arguments:

var int1;

var int2;

var hour;

var min;

var sec;

var str;



var file = Clib.fopen("c:\\temp\\fscanf.txt", "r");

TheApplication().TraceOn("c:\\temp\\testoutput.txt", "allocation", "all");



// Simple scanf:

// input line e.g.: "Monday 10:18:00"

Clib.fscanf(file, "%s %i:%i:%i\n", str, hour, min, sec);

TheApplication().Trace(str + ", " + hour + ", " + min + ", " + sec);



// Using width specifier:

// input line e.g.: "1234567890"

Clib.fscanf(file, "%5i%5i\n", int1, int2);

TheApplication().Trace(int1 + ", " + int2);



// Reading hexadecimal integers and suppressing assignment to a variable:

// input line e.g.: "AB3F 456A 7B44"

Clib.fscanf(file, "%x %*x %x\n", int1, int2);

TheApplication().Trace(int1 + ", " + int2);



// Using character ranges:

// input line e.g.: "helloHELLO"

Clib.fscanf(file, "%[a-z]\n", str);

TheApplication().Trace(str);



Clib.fclose(file);

This example produces the following output:

COMMENT,"Monday, 10, 18, 0"

COMMENT,"12345, 67890"

COMMENT,"43839, 31556"

COMMENT,hello

Clib Scan and Convert from Input Device Method

The Clib Scan and Convert from Input Device method reads input from an input device and stores the data in arguments. It reads from the keyboard unless the Clib Reopen File method redirects it to another file as stdin. It returns one of the following values:

If successful, then it returns the number of variables where it assigned data.
If not successful, then it returns the following value:
EOF

This method does not read the input until the user presses the ENTER key. This method is identical to the Clib Scan and Convert File method with stdin set as the first argument. For more information, see Clib Scan and Convert File Method.

Format

Clib.sscanf([formatString] [,var1, var2, ..., varn])

Clib Unget Method

The Clib Unget method pushes a character back into a file. It returns one of the following values:

If successful, then it returns the value that the char argument contains.
If not successful, then it returns the following value:
EOF

If this method pushes a character back into a file, then it converts the character that you specify in the char argument to a byte. It only pushes back one character. After the unget, this character is again available in the file for subsequent retrieval. You might need to use this method to read up to, but not including, a newline character. You can then use it to push the newline character back into the file buffer.

Format

Clib.ungetc(char, filePointer)

The following table describes the arguments for the Clib Unget method.

Argument	Description
char	The character that this method pushes back. It puts back one character to the file stream that it reads. It moves the seek position of the file pointer by one character position.
filePointer	A file pointer that the Clib Open File method returns.

Clib Write Character Method

The Clib Write Character method writes a character, converted to a byte, to a file that you specify. It returns one of the following values:

If successful, then it returns the value that the char argument contains.
If not successful, then it returns the following value:
EOF

The following type of character that the char argument contains determines how this method writes the character:

String. It writes the first character of the string to the file.
Number. It writes the character that corresponds to the Unicode value for this number to the file.

Format

Clib.fputc(char, filePointer)

Clib.putc(char, filePointer)

Clib.fputc writes a character to a file. Clib.putc writes a character to the screen. In most situations, to avoid an error with macro usage, you must use Clib.fputc.

The following table describes the arguments for the Clib Write Character method.

Argument	Description
char	A one character string or variable that contains a single character.
filePointer	A file pointer that the Clib Open File method returns.

Clib Write Formatted String Method

The Clib Write Formatted String method writes a formatted string to a file.

Format

Clib.fprintf(filePointer, formatString)

The following table describes the arguments for the Clib Write Formatted String method.

Argument	Description
filePointer	A file pointer that the Clib Open File method returns.
formatString	A string that contains formatting instructions for each data item that the Clib Write Formatted String method writes. For more information, Format Characters for Methods That Print and Scan.

Example

The following example uses the Clib Write Formatted String method with various values for the formatString argument:

function Service_PreInvokeMethod (MethodName, Inputs, Outputs)

{

   if (MethodName == "fprintfsamples") 

   {

      var intgr = 123456789;

      var flt = 12345.6789;

      var hour = 1;

      var min = 7;

      var sec = 0;

      var str = "Hello World";

      var file = Clib.fopen("c:\\temp\\fprintf.txt", "w");



      // Simple formatting:

      Clib.fprintf(file, "(1) %s, it is now %i:%i:%i pm.\n", str, hour, min, sec);

      Clib.fprintf(file, "(2) The number %i is the same as %x.\n", intgr, intgr);

      Clib.fprintf(file, "(3) The result is %f.\n", flt);



      // Flag values:

      // "+" forces a + or - sign; "#" modifies the type flag "x" 
      // to prepend "0x" to the output. (Compare with the simple

      // formatting example.)

      Clib.fprintf(file, "(4) The number %+i is the same as %#x.\n", intgr, intgr);



      // Width values:

      // The width is a minimal width, thus longer values

      // are not truncated.

      // "2" fills with spaces, "02" fills with zeros.

      var myWidth = 2;

      Clib.fprintf(file, "(5) %5s, it is now %2i:%02i:%02i pm.\n", str, hour, min, 
      sec);



      // Precision values:

      // ".2" restricts to 2 decimals after the decimal separator.

      // The number will be rounded appropriately.

      Clib.fprintf(file, "(6) The result is %.2f.\n", flt);



      // A combined example:

      // <space> displays  space or minus; 

      // "+" displays  plus or minus;

      // "020" uses a minimal width of 20, padded with zeros;

      // ".2" displays 2 digits after the decimal separator;

      // "*" uses the next argument in the list to specify the width.

      Clib.fprintf(file, "(7) The values are:\n%+020.2f\n% 020.2f\n% *.2f", flt, 
      intgr, 20, intgr);



      Clib.fclose(file);



      return (CancelOperation);

   } 

   return (ContinueOperation);

}

This example produces the following output:

(1) Hello World, it is now 1:7:0 pm.

(2) The number 123456789 is the same as 75bcd15.

(3) The result is 12345.678900.

(4) The number +123456789 is the same as 0x75bcd15.

(5) Hello World, it is now  1:07:00 pm.

(6) The result is 12345.68.

(7) The values are:

+0000000000012345.68

0000000123456789.00

123456789.00

Clib Write String to File Method

The Write String to File method writes a string to a file that you specify. It returns one of the following values:

If successful, then it returns a nonnegative value.
If not successful, then it returns the following value:
EOF

Format

Clib.fputs(string, filePointer)

The following table describes the arguments for the Write String to File method.

Argument	Description
string	A string literal or a variable that contains a string.
filePointer	A file pointer that the Clib Open File method returns.

Example

For an example, see Clib Get Characters to Next Line Method.

Clib Write to File Method

The Clib Write to File method writes data to a file. It returns one of the following values:

If successful, then it returns the number of elements it wrote
If not successful, then it returns the following value:
0

Siebel eScript usage of fwrite differs from the standard C library usage. The C library writes arrays of numeric values or structures from consecutive bytes in memory. This is not necessarily true in Siebel eScript.

Format A

Clib.fwrite(sourceVar, varDescription, filePointer)

Clib.fwrite(sourceVar, bytelength, filePointer)

The following table describes the arguments for the Clib Write to File method.

Argument	Description
bytelength	Number of bytes that this method writes.
sourceVar	The source that this method uses to get the data that it writes.
varDescription	A value that depends on the type of object that the sourceVar argument identifies.
filePointer	The file where this method writes data.

Usage for the varDescription Argument

The following table describes values you must set for the sourceVar argument and the varDescription argument. For example, if you use the sourceVar argument to identify a buffer, then you must set the varDescription argument to the length of that buffer, in bytes.

Value of the sourceVar Argument	Value of the varDescription Argument
Buffer	Length of the buffer, in bytes.
Object	Value of the object descriptor.
A single datum	One of the values listed in Clib Read From File Method.

Example

The following example writes the following data into the fp file:

The 16-bit i integer
The 32-bit f float
The 10-byte buf buffer:

if ( !Clib.fwrite(i, SWORD16, fp) || !Clib.fwrite(f, FLOAT32, fp)

            || 10 !=  fwrite(buf, 10, fp))

{

   TheApplication().RaiseErrorText("Error writing to file.\n");

}

Clib String Methods

This topic describes Clib string methods. It includes the following topics:

Clib Append String Method

The Clib Append String method copies characters from one string to the end of another string. It appends up to the value that you specify in the maxLen argument of the string that you specify in the sourceString argument. It does not copy any character that occurs after a null byte. It returns the appended string that the destString argument contains.

The length of the destString argument is the lesser of the maxLen argument or the length of the sourceString argument.

Format

Clib.strncat(destString, sourceString, maxLen)

The following table describes the arguments for the Clib Append String method.

Argument	Description
sourceString	The string that this method uses to get the characters that it adds.
destString	The string where this method adds characters.
maxLen	The maximum number of characters to add.

Example

The following example uses the Clib Append String method:

var string1 = "I love to ";

var string2 = "ride hang-gliders and motor scooters.";

Clib.strncat(string1, string2, 17);

TheApplication().RaiseErrorText(string1);

This example returns the following string:

"I love to ride hang-gliders"

For more information, see Clib Copy String Method.

Clib Compare Strings Method

The Clib Compare Strings method performs a comparison between two strings, one byte at a time. It returns one of the following values:

If the strings are identical, then it returns the following value:
0
If the ASCII code of the first unmatched character in the string1 argument is:
- Less than that of the first unmatched character in the string2 argument, then it returns a negative number.
- Greater than that of the first unmatched character in the string2 argument, then it returns a positive number.

It stops the comparison if one of the following situations occurs:

It encounters a mismatch between strings.
It encounters a terminating null byte.

Format

Clib.stricmp(string1, string2)

Clib.strcmpi(string1, string2)

Clib.strncmp(string1, string2, maxLen)

Clib.strncmpi(string1, string2, maxLen)

Clib.strnicmp(string1, string2, maxLen)

You can use one of the following:

Search that is case-sensitive. You use Clib.strncmp.
Search that is not case-sensitive. You use Clib.stricmp or Clib.strcmpi. In a comparison that is not case-sensitive, A and a are the same.

The Clib.strncmp, Clib.strncmpi, and Clib.strnicmp methods stop the comparison when one of the following situations occurs:

It has compared the number of bytes that you specify in the maxLen argument.
It encounters a terminating null byte.

The following table describes the arguments for the Clib Compare Strings method.

Argument	Description
string1	A string or a variable that contains a string that this method compares against the string that the string2 argument contains.
string2	A string or a variable that contains a string that this method compares against the string that the string1 argument contains.
maxLen	The number of bytes to compare.

Clib Convert String to Lowercase Method

The Clib Convert String to Lowercase method converts a string to lowercase. It starts at position 0 of the str argument and ends immediately before the terminating null byte. It returns the value of the str argument all in lowercase.

Format

Clib.strlwr(str)

The following table describes the arguments for the Clib Convert String to Lowercase method.

Argument	Description
str	The string that this method modifies to lowercase.

Clib Copy String Method

The Clib Copy String method copies characters from one string to another string. It returns the ASCII code of the first character of the string that you specify in the destString argument. You can write code that copies from one part of a string to another part of the same string.

Format

Clib.strncpy(destString, sourceString, maxLen)

This method uses the same arguments as the Clib Append String method. For more information, see Clib Append String Method. Note the following differences that the Clib Copy String method performs:

The number of characters it copies is the lesser of the value of the maxLen argument and the length of the sourceString argument.
If the value that the MaxLen argument contains is greater than the length of the value that the sourceString argument contains, then it fills the remainder of the destination string with null bytes.
If the string you specify in the destString argument is not defined, then it defines this string.

Clib Get Formatted String Method

The Clib Get Formatted String method returns a formatted string as a numeric literal or as an argument.

If you use this method to format a floating point number to a specific number of decimal points, then it returns the value rounded to the number of decimal points that you specify. For example, if you use the following code to format the num argument, then it returns the num argument rounded to 2 decimal points:

Clib.rsprintf(“%.2f”, num)

Format

Clib.rsprintf([formatString] [,var1, var2, ..., varn])

The following table describes the arguments for the Clib Get Formatted String method.

Argument	Description
formatString	A string that includes character combinations that describe how to treat arguments. For more information on the format strings you can use with this method, see Format Characters for Methods That Print and Scan.
var1, var2, ..., varn	Variables that this method formats according to the format that you define in the formatString argument.

Example

Each of the following code lines includes an example of using the Clib Get Formatted String method followed by the resulting string:

var TempStr = Clib.rsprintf("I count: %d %d %d.",1,2,3) //"I count: 1 2 3"

var a = 1;

var b = 2;

TempStr = Clib.rsprintf("%d %d %d",a, b, a+b) //"1 2 3"

Clib Get Last Substring Method

The Clib Get Last Substring method searches a string for the last occurrence of a character. It returns one of the following values:

If it finds the character, then it returns a string that includes the following items:
Begins at the rightmost occurrence of the value that you specify in the char argument
Ends with the rightmost character of the string that you specify in the string argument
If it does not find the character, then it returns the following value:

Null

It is recommended that you use the Clib Get Last Substring method only if you cannot use the equivalent standard JavaScript method.

Format

Clib.strrchr(string, char)

The following table describes the arguments for the Clib Get Last Substring method.

Argument	Description
string	A string literal or string variable that contains the character that this method searches.
char	The character that this method searches for.

Example

The following example uses the Clib Get Last Substring method:

var str = "I don’t like soggy cereal." 

var substr = Clib.strrchr(str, 'o'); 

TheApplication().RaiseErrorText("str = " + str + "\nsubstr = " + substr);

This example provides the following result:

str = I don’t like soggy cereal.

substr = oggy cereal.

For more information, see Create String From Substring Method.

Clib Get Substring Method

The Clib Get Substring method searches a string for the first occurrence of a string. It returns one of the following values:

If it finds the string that you specify in the findString argument, then it returns the string that:
- Begins at the first occurrence of the value that you specify in the findString argument.
- Ends at the end of the string that you specify in the sourceString argument.
If it does not find the string that you specify in the findString argument, then it returns the following value:
Null

It searches the string that you specify in the sourceString argument from the beginning of this string.

It is recommended that use the Clib Get Substring method only if you cannot use the equivalent standard JavaScript method.

Format

Clib.strstr(sourceString, findString)

Clib.strstri(sourceString, findString)

You can use one of the following:

Search that is case-sensitive. You use Clib.strstr.
Search that is not case-sensitive. You use Clib.strstri.

The following table describes the arguments for the Clib Get Substring method.

Argument	Description
sourceString	The string that this method searches.
findString	The string that this method must find.

Example 1

The following example uses Clib.strstr:

function Test1_Click ()

{

   var str = "We have to go to Haverford."

   var substr = Clib.strstr(str, 'H'); 

   TheApplication().RaiseErrorText("str = " + str + "\nsubstr = " +substr);

}

This example provides the following result:

str = We have to go to Haverford

substr = Haverford

The following example uses Clib.strstri:

function Test_Click ()

{

   var str = "We have to go to Haverford."

   var substr = Clib.strstri(str, 'H'); 

   TheApplication().RaiseErrorText("str = " + str + "\nsubstr = " +substr);

}

This example provides the following result:

str = We have to go to Haverford.

substr = have to go to Haverford.

For more information, see Create String From Substring Method.

Clib Search String for Character Method

The Clib Search String for Character method searches a string for a character that you specify. It returns one of the following values:

If it finds the character, then it returns the offset of the first occurrence of the character that you specify in the char argument. This offset is the number of characters in the string from the beginning to the first occurrence, starting with 0.
If it does not find the character, then it returns the following value:
Null

It is recommended that you use the Clib Search String for Character method only if you cannot use the equivalent standard JavaScript method.

Format

Clib.strchr(string, char)

The following table describes the arguments for the Clib Search String for Character method.

Argument	Description
string	A string literal or a string variable that contains the character for which this method searches.
char	The character for which this method searches.

Example

The following example uses the Clib Search String for Character method:

var str = "I can't stand soggy cereal." 

var substr = Clib.strchr(str, 's'); 

TheApplication().RaiseErrorText("str = " + str + "\nsubstr = " + substr);

This example products the following results:

I can't stand soggy cereal.

stand soggy cereal.

Clib Search String for Character Set Method

The Clib Search String for Character Set method searches a string for a set of characters that you specify in the charSet argument. It returns one of the following values:

If it finds this set, then it returns the offset of the first character of the first occurrence of the set that you specify in the charSet argument. This offset is the number of characters in the string from the beginning to the first occurrence, starting with 0.
If it does not find this set, then it returns the length of the string.

Format

Clib.strcspn(string, charSet)

Clib.strpbrk(string, charSet)

Clib.strcspn is similar to Clib.strpbrk, except that Clib.strpbrk returns the set that begins at the first character found while Clib.strcspn returns the offset number for that character.

The following table describes the arguments for the Clib Search String for Character Set method.

Argument	Description
string	A literal string or a variable that contains the character set for which this method searches.
charSet	A literal string or a variable that is the character set for which this method searches.

Usage for the Clib Search String for Character Set Method

The Clib Search String for Character Set method searches for characters starting at the beginning of the string that you specify in the string argument. The search is case-sensitive, so you must use uppercase and lowercase characters in the charSet argument.

It is recommended that you use the Clib Search String for Character Set Method method only if you cannot use the equivalent standard JavaScript method.

Example

The following example demonstrates the difference between Clib.strcspn and Clib.strpbrk:

var string = "There's more than one way to climb a mountain.";

var rStrpbrk = Clib.strpbrk(string, "dxb8w9k!"); 

var rStrcspn = Clib.strcspn(string, "dxb8w9k!"); 

TheApplication().RaiseErrorText("The string is: " +  string +

   "\nstrpbrk returns a string: " +  rStrpbrk +

   "\nstrcspn returns an integer: " +  rStrcspn);

This example provides the following results:

The string is: There’s more than one way to climb a mountain.

strpbrk returns a string: way to climb a mountain.

strcspn returns an integer: 22

Clib Search String for Not Character Set Method

The Clib Search String for Not Character Set method searches a string for a set of characters that is not part of the value that you specify in the charSet argument. It returns one of the following values:

If it finds all characters of the string that you specify in the charSet argument, then it returns the length of the string.
If it does not find all characters of the string that you specify in the string argument, then it returns the offset of the first character that is not a member of the character set that you specify in the charSet argument.

Format

Clib.strspn(string, charSet)

This method uses the same arguments as the Clib Search String for Character Set method. Usage is also the same. For more information, see the following topics:

Clib Search String for Character Set Method

Example

The following example searches for the value in the string argument, and then returns the position of w, counting from 0:

var string = "There is more than one way to swim.";

var rStrspn = Clib.strspn(string, " aeiouTthrsmn"); 

TheApplication().RaiseErrorText("strspn returns an integer: " + rStrspn);

This example provides the following results:

strspn returns an integer: 23

Clib Write Formatted String Method

The Clib Write Formatted String method writes output to a string variable according to a format that you define. It returns one of the following values:

If successful, then it returns the number of characters it wrote in the buffer.
If not successful, then it returns the following value:
EOF

You are not required to define the string value. It is large enough to hold the result.

Format

Clib.sprintf(stringVar, formatString, var1, var2, ..., varn)

This method performs the same work and uses the same arguments as the Clib Formatted String method except it also includes the stringVar argument. This argument identifies the name of the variable where the Clib Write Formatted String method writes the formatted string. For more information, Clib Get Formatted String Method.

Example

The following example uses the Clib Write Formatted String method with various format string arguments:

TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");

     

var a, b, c;

a = 5;

b = 2;



Clib.sprintf(c, "First # %d + Second # %d is equal to %03d",a,b, a+b); 

TheApplication().Trace("Output : " + c);



Clib.sprintf(c, "\n First # %d \n Second # %d \n => %d",12,16, 12+16) 

TheApplication().Trace("Output : " + c);



var x, y, z, n;

var x = "Ali is 25 years old";

var y = "he lives in Ireland.";

var n = Clib.sprintf(z, "\n %s and %s",x,y)  ;



TheApplication().Trace("Output : " + z);

TheApplication().Trace("Total characters: " + n);



var  a = 16.51;

var  b = 5.79;

var c;



Clib.sprintf(c, "%.3f / %.3f is equal to %0.3f",a,b, parseFloat(a/b)); 

TheApplication().Trace("Output : " + c);



TheApplication().TraceOff();

This example produces the following result:

02/18/04,18:37:35,START,7.5.3 [16157] LANG_INDEPENDENT,SADMIN,3964,3836

02/18/04,18:37:35,COMMENT,Output : First # 5 + Second # 2 is equal to 007

02/18/04,18:37:35,COMMENT,"Output : 

 First # 12 

 Second # 16 

 => 28"

02/18/04,18:37:35,COMMENT,"Output : 

 Ali is 25 years old and he lives in Ireland."

02/18/04,18:37:35,COMMENT,Total characters: 46

02/18/04,18:37:35,COMMENT,Output : 16.510 + 5.790 is equal to 2.851

02/18/04,18:37:35,STOP

Clib Buffer Methods

This topic describes Clib buffer methods. It includes the following topics:

Clib Get Memory Method

The Clib Get Memory method searches a buffer for the first occurrence of a character that you specify. It returns one of the following values:

If it finds the character you specify, then it returns the contents of the buffer starting at that character.
If it does not find the character you specify, then it returns the following value:
Null

Format

Clib.memchr(bufferVar, char[, size])

The following table describes the arguments for the Clib Get Memory method.

Argument	Description
bufferVar	A buffer or a variable that references a buffer.
char	The character that this method attempts to locate.
size	The number of bytes of the buffer that this method searches. It does one of the following depending on if you specify a size: You do specify a size. It searches at the beginning of the buffer and continues until it reaches the point in the buffer that you indicate in the size argument. For example, if you specify the size as 1024, then it searches the first 1024 bytes of the buffer. You do not specify a size. It searches the entire buffer from the first byte.

Argument

Description

bufferVar

A buffer or a variable that references a buffer.

char

The character that this method attempts to locate.

size

The number of bytes of the buffer that this method searches. It does one of the following depending on if you specify a size:

You do specify a size. It searches at the beginning of the buffer and continues until it reaches the point in the buffer that you indicate in the size argument. For example, if you specify the size as 1024, then it searches the first 1024 bytes of the buffer.
You do not specify a size. It searches the entire buffer from the first byte.

Clib Compare Memory Method

The Clib Compare Memory method compares the contents of two buffers. It returns one of the following values:

If the value in the buf1 argument is less than the value in the buf2 argument, then it returns a negative number.
If the value in the buf1 argument is greater than the value in the buf2 argument, then it returns a positive number.
If the value in the buf1 argument is the same as the value in the buf2 argument, then it returns 0.

Format

Clib.memcmp(buf1, buf2[, length])

The following table describes the arguments for the Clib Compare Memory method.

Argument	Description
buf1	A variable that contains the name of a buffer.
buf2	A variable that contains the name of a buffer.
length	The number of bytes that this method compares. It does one of the following depending on how you specify the length argument: You specify the length argument. It compares the buffers from the first byte up to the length that you specify. For example, if you specify 1024 as the length, then it compares the first 1024 bytes of the buffer. You do not specify the length argument. It compares the full length of the buffers. If one buffer is shorter than the other buffer, then it compares the buffers from the beginning byte up to the length of the shorter buffer.

Argument

Description

buf1

A variable that contains the name of a buffer.

buf2

A variable that contains the name of a buffer.

length

The number of bytes that this method compares. It does one of the following depending on how you specify the length argument:

You specify the length argument. It compares the buffers from the first byte up to the length that you specify. For example, if you specify 1024 as the length, then it compares the first 1024 bytes of the buffer.
You do not specify the length argument. It compares the full length of the buffers.

If one buffer is shorter than the other buffer, then it compares the buffers from the beginning byte up to the length of the shorter buffer.

Clib Copy Memory Method

The Clib Copy Memory method copies bytes from a source buffer to a destination buffer.

Format

Clib.memcpy(destBuf, srcBuf[, length])

Clib.memmove(destBuf, srcBuf[, length])

Siebel eScript protects data from being overwritten, so Clib.memmove performs exactly the same work as Clib.memcpy.

The following table describes the arguments for the Clib Copy Memory method.

Argument	Description
destBuf	The name of a buffer or a variable that references a buffer. If this buffer does not exist, then this method creates it.
srcBuf	The buffer that this method uses to get the data that it copies.
length	The number of bytes that this method copies. If you do not specify the length argument, then it copies the entire contents of the buffer.

Clib Set Memory Method

The Clib Set Memory method sets the bytes in a buffer to a character that you specify.

Format

Clib.memset(bufferVar, char[, length])

The following table describes the arguments for the Clib Set Memory method.

Argument	Description
bufferVar	The name of a buffer or a variable that references a buffer. If this buffer does not exist, then this method creates it.
char	The character to which this method sets the bytes of the buffer.
length	The number of bytes that this method writes. This method does one of the following: If the buffer is shorter than the value you specify in the length argument, then it increases the size of this buffer so that the size is equal to the value in the length argument. If you do not specify the length argument, then it sets the length argument to the size of the buffer, starting at position 0.

Argument

Description

bufferVar

The name of a buffer or a variable that references a buffer. If this buffer does not exist, then this method creates it.

char

The character to which this method sets the bytes of the buffer.

length

The number of bytes that this method writes. This method does one of the following:

If the buffer is shorter than the value you specify in the length argument, then it increases the size of this buffer so that the size is equal to the value in the length argument.
If you do not specify the length argument, then it sets the length argument to the size of the buffer, starting at position 0.

Clib Mathematical Methods

This topic describes Clib mathematical methods. It includes the following topics:

Clib Create Random Number Method

The Clib Create Random Number method creates a pseudo-random number between 0 and RAND_MAX, inclusive. The value of RAND_MAX depends on the operating system. It is typically 32,768.

The initial value of the random number generator and earlier calls to the Clib Create Random Number method affects the sequence of pseudo-random numbers. For more information, see Clib Initialize Random Number Generator Method.

Format

Clib.rand()

For more information, see Get Random Number Method.

Clib Divide Method

The Clib Divide method performs integer division and returns a quotient and remainder.

Format

Clib.div(numerator, denominator)
Clib.ldiv(numerator, denominator)

Siebel eScript does not distinguish between integers and long integers, so clib.div and clib.ldiv are identical.

The following table describes the arguments for the Clib Divide method.

Argument	Description
numerator	The number that this method divides.
denominator	The number by which this method divides the numerator.

Clib Divide Method describes the structure of the return value.

Element	Description
.quot	quotient
.rem	remainder

Example

The following example accepts two numbers as input from the user, divides the first number by the second number, and then displays the result:

var division = Clib.div(ToNumber(n), ToNumber(d));

   TheApplication().RaiseErrorText("The quotient is " + division.quot + ".\n\n" + 
"The remainder is " + division.rem + ".");

If run this example with the values of n=9 and d=4, then it produces the following result:

The quotient is 2.

The remainder is 1.

Clib Get Floating Point Number Method

The Clib Get Floating Point Number method calculates a floating-point number given a mantissa and an exponent. It returns the result of the calculation. It calculates a floating-point number from the following equation:

mantissa multiplied by 2 ^ exponent

This method is the inverse of the Get Normalized Mantissa method. For more information, see Clib Get Normalized Mantissa Method.

Format

Clib.ldexp(mantissa, exponent)

The following table describes the arguments for the Clib Get Floating Point Number method.

Argument	Description
mantissa	The number on which this method operates.
exponent	The exponent that this method uses.

Clib Get Hyperbolic Cosine Method

The Clib Get Hyperbolic Cosine method calculates and returns the hyperbolic cosine of x.

Format

Clib.cosh(number)

The following table describes the arguments for the Clib Get Hyperbolic Cosine method.

Argument	Description
number	The hyperbolic cosine of the number that this method returns.

Clib Get Hyperbolic Sine Method

The Clib Get Hyperbolic Sine method calculates and returns the hyperbolic sine of a floating point number.

Format

Clib.sinh(floatNum)

The following table describes the arguments for the Clib Get Hyperbolic Sine method.

Argument	Description
floatNum	A floating-point number or a variable that contains a floating-point number. This method calculates the hyperbolic sine of this number.

Clib Get Hyperbolic Tangent Method

The Clib Get Hyperbolic Tangent method calculates and returns the hyperbolic tangent of a floating-point number.

Format

Clib.tanh(floatNum)

The following table describes the arguments for the Clib Get Hyperbolic Tangent method.

Argument	Description
floatNum	A floating-point number or a variable that contains a floating-point number that this method calculates.

Clib Get Integer Method

The Clib Get Integer method calculates and returns the integer part of a decimal number. The effect is identical to that of the Convert Value to Integer method. For more information, see Convert Value to Integer Method.

Format

Clib.modf(number, var intVar)

The following table describes the arguments for the Clib Get Integer method.

Argument	Description
number	The floating-point number that this method splits.
intVar	Contains the integer part of the number.

Example

The following example passes the same value to the Clib Get Integer method and to the Convert Value to Integer method. The result is the same for each method:

function eScript_Click ()

{

   Clib.modf(32.154, var x);

   var y = ToInteger(32.154);

   TheApplication().RaiseErrorText("modf yields " + x + 

         ".\nToInteger yields " + y + ".");

}

This example produces the following result:

modf yields 32

ToInteger yields 32.

Clib Get Normalized Mantissa Method

The Clib Get Normalized Mantissa method converts a number into a normalized mantissa in a value in the range of 0.5 through 1.0, and then calculates an integer exponent of 2 so that the number is equivalent to the following value:

mantissa multiplied by 2 ^ exponent

It returns one of the following values:

A normalized mantissa in the range of 0.5 through 1.0
0

A mantissa is the decimal part of a natural logarithm.

Format

Clib.frexp(number, exponent)

The following table describes the arguments for the Clib Get Normalized Mantissa method.

Argument	Description
number	The number on which this method operates.
exponent	The exponent that this method uses.

Clib Initialize Random Number Generator Method

The Clib Initialize Random Number Generator method initializes a random number generator.

Format

Clib.srand(seed)

The following table describes the arguments for the Clib Initialize Random Number Generator method.

Argument

Description

seed

The number that the random number generator uses as a starting point.

If you do not specify the seed argument, then this method uses a random number that is specific to the operating system.

Clib Date and Time Methods

This topic describes Clib date and time methods. It includes the following topics:

Overview of Clib Date and Time Methods

The Clib time object measures time in the following ways:

As an integral value of the number of seconds that have occurred since January 1, 1970.
As a time object that includes properties for the day, month, year, and so on. This time object is distinct from the standard JavaScript date object.

Note the following:

The time object is for use with the date and time functions in the Clib object.
You cannot write code that uses a date object property with a time object or a time object property with a date object.
Although the time object is different than the date object, these objects contain similar data.

The following table information lists the integer properties for the timeInt argument of the Clib time object.

Value for the timeInt Argument	Integer Property
tm_sec	Second after the minute, from 0.
tm_min	Minutes after the hour, from 0.
tm_hour	Hour of the day, from 0.
tm_mday	Day of the month, from 1.
tm_mon	Month of the year, from 0.
tm_year	Years since 1900, from 0.
tm_wday	Days since Sunday, from 0.
tm_yday	Day of the year, from 0.
tm_isdst	Flag for Daylight Savings Time.

Clib Convert Integer to GMT Method

The Clib Convert Integer to GMT method uses the integer value that the Clib Convert Time to Integer method returns and converts it to a time object that includes the current date and time expressed as Greenwich mean time (GMT).

It is recommended that you use the Clib Convert Integer to GMT method only if you cannot use the equivalent standard JavaScript method. Note the following code:

var now = Clib.asctime(Clib.gmtime(Clib.time())) + "GMT";

This code is exactly equivalent to the following standard JavaScript code:

var aDate = new Date;

var now = aDate.toGMTString()

Format

Clib.gmtime(timeInt)

This method uses the same arguments as the Clib Get Date and Time method. For more information, see Clib Get Date and Time Method.

Example

The following example returns the current GMT date and time:

TheApplication().RaiseErrorText(Clib.asctime(Clib.gmtime(Clib.time())));

It returns this value as a string that uses the following format:

Day Mon dd hh:mm:ss yyyy:

Clib Convert Integer to Local Time Method

The Clib Convert Integer to Local Time method returns the value of the timeInt argument as a time object. It is recommended that you use this method only if you cannot use the equivalent standard JavaScript method. Note the following code:

var now = Clib.asctime(Clib.localtime(Clib.time()));

This code is exactly equivalent to the following standard JavaScript code:

var aDate = new Date;
var now = aDate.toLocaleString()

Format

Clib.localtime(timeInt)

This method uses the same arguments as the Clib Get Date and Time method. For more information, see Clib Get Date and Time Method.

Clib Convert Time to Integer Method

The Clib Return Time in Integers method returns the current time expressed in integers. The time format is not specifically defined except that it includes the current time according to the closest approximation that the operating system can make.

The following code assigns the current local time to the timeInt argument:

Clib.time(timeInt) and timeInt = Clib.time()

Format

Clib.time([[var] timeInt])

The following table describes the arguments for the Return Time in Integers method.

Argument	Description
timeInt	Holds the value that this method returns. You must declare this argument as a variable.

Example

For examples, see the following topics:

Clib Convert Time Object to Integer Method

The Clib Convert Time Object to Integer method converts a time object to the time format that the Clib Convert Time to Integer method returns. It returns one of the following values:

If it can convert the value in the Time argument, then it returns the value that the Time argument contains expressed as an integer.
If it cannot convert the value in the Time argument, then it returns negative 1.

It sets any element of the Time argument that is not defined to 0 before it performs the conversion. This method is the opposite of the Convert Integer to Local Time method that converts a time integer to a time object.

Format

Clib.mktime(Time)

The following table describes the arguments for the Clib Convert Time Object to Integer method.

Argument	Description
Time	A time object.

Example

The following example uses the Clib Convert Time Object to Integer method to format a time so that Siebel eScript can use it with the Clib Get Difference in Seconds method:

// create time object and set time to midnight:

var midnightObject = Clib.localtime(Clib.time());

midnightObject.tm_hour = 0;

midnightObject.tm_min = 0;

midnightObject.tm_sec = 0;



// use mktime to convert Time object to integer:

var midnight = Clib.mktime(midnightObject);



// difftime can now use this value:

var diff = Clib.difftime(Clib.time(), midnight);

TheApplication().Trace("Seconds since midnight: " + diff);

This example produces the following result:

COMMENT,Seconds since midnight: 59627

For an example that describes the difference between the formats that asctime and mktime use, see Clib Get Date and Time Method.

Clib Get Date and Time Method

The Clib Get Date and Time method returns a string that includes the date and time that it extracts from a time object. The string it returns uses the following format:

Day Mon dd hh:mm:ss yyyy

For example, Wed Aug 10 13:21:56 2005.

Format

Clib.asctime(Time)

The following table describes the arguments for the Clib Get Date and Time method.

Argument	Description
Time	A time object.

Example

The following example describes the difference between the asctime and mkdir formats for time:

TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");

     

var tm = Clib.localtime(Clib.time());

var tmStr = Clib.asctime(tm);

var tmVal = Clib.mktime(tm); 



TheApplication().Trace("Time String : " + tmStr);

TheApplication().Trace("Time Value  : " + tmVal);



TheApplication().TraceOff();

This example produces the following result:

03/05/04,12:26:30,START,7.5.3 [16157] LANG_INDEPENDENT,SADMIN,6532,6584

03/05/04,12:26:30,COMMENT,"Time String : Fri Mar 05 12:26:30 2004"

03/05/04,12:26:30,COMMENT,Time Value  : 1078489590

03/05/04,12:26:30,STOP

For more information, see the following topics:

Clib Get Formatted Date and Time Method

The Clib Get Formatted Date and Time method creates a string that includes the date, time, or the date and time. It returns a formatted string that contains these values.

Format

Clib.strftime(stringVar, formatString, Time)

The following table describes the arguments for the Clib Get Formatted Date and Time method.

Argument	Description
stringVar	A variable that holds the time in a string.
formatString	A string that describes how to format the value in the stringVar argument. Conversion characters represent this format. For more information, see the following section.
Time	A time object that the Clib Convert Integer to Local Time method returns. For more information on the time object, see Overview of Clib Date and Time Methods.

Conversion Characters That the Return Formatted Date and Time Method Uses

The following table describes conversion characters that the Return Formatted Date and Time method uses.

Character	Description	Example
%a	Abbreviated weekday name.	Sun
%A	Full weekday name.	Sunday
%b	Abbreviated month name.	Dec
%B	Full month name.	December
%c	Date and time.	Dec 2 06:55:15 1979
%d	Two digit day of the month.	02
%H	Two digit hour of the 24-hour day.	06
%I	Two digit hour of the 12-hour day.	06
%j	Three digit day of the year from 001.	335
%m	Two digit month of the year from 01.	12
%M	Two digit minute of the hour.	55
%p	AM or PM.	AM
%S	Two digit seconds of the minute.	15
%U	Two digit week of the year where Sunday is the first day of the week.	48
%w	Day of the week where Sunday is 0.	0
%W	Two digit week of the year where Monday is the first day of the week.	47
%x	The date.	Dec 2 1979
%X	The time.	06:55:15
%y	Two digit year of the century.	79
%Y	The year.	1979
%Z	The name of the time zone, if known.	EST
%%	The percentage symbol.	%

Example 1

The following example displays the full day name and month name of the current day:

var TimeBuf;

Clib.strftime(TimeBuf,"Today is %A, and the month is %B",

   Clib.localtime(Clib.time()));

TheApplication().RaiseErrorText(TimeBuf);

The display is similar to the following:

Today is Friday, and the month is July

The following example uses various conversion characters to format the value that the Clib Get Formatted Date and Time method returns:

TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");

     

var tm, tmStrFmt;

tm = Clib.localtime(Clib.time());



Clib.strftime(tmStrFmt, "%m/%d/%Y",tm);

TheApplication().Trace("Time String Format: " + tmStrFmt);



Clib.strftime(tmStrFmt, "%A %B %d, %Y",tm);

TheApplication().Trace("Time String Format: " + tmStrFmt);



TheApplication().TraceOff();

This example produces the following result:

03/05/04,12:44:01,START,7.5.3 [16157] LANG_INDEPENDENT,SADMIN,6848,6708

03/05/04,12:44:01,COMMENT,Time String Format: 03/05/2004

03/05/04,12:44:01,COMMENT,"Time String Format: Friday March 05, 2004"

03/05/04,12:44:01,STOP

Clib Get Local Date and Time Method

The Clib Get Local Date and Time method returns a string that includes the date and time, adjusted for the local time zone. It is equivalent to the following code:

Clib.asctime(Clib.localtime(timeInt));

where:

timeInt is the date and time that the Clib Get Date and Time method returns.

Format

Clib.ctime(timeInt)

The following table describes the arguments for the Clib Get Local Date and Time method.

Argument	Description
timeInt	The date and time value that this method returns.

Example

The following example returns the current date and time:

TheApplication().RaiseErrorText(Clib.ctime(Clib.time()));

It returns this date and time in a string that uses the following format:

Day Mon dd hh:mm:ss yyyy

Clib Get Difference in Seconds Method

The Clib Get Difference in Seconds method returns the difference in seconds between two times.

Format

Clib.difftime(timeInt1, timeInt0)

The following table describes the arguments for the Clib Get Difference in Seconds method.

Argument	Description
timeInt0	An integer time value that this method returns.
timeInt1	An integer time value that this method returns.

Example

The following example displays the difference in seconds between two times:

function difftime_Click ()

{

   var first = Clib.time();

   var second = Clib.time();

TheApplication().RaiseErrorText("Elapsed time is " +

      Clib.difftime(second, first) + " seconds."); 

}

Clib Get Tick Count Method

The Clib Get Tick Count method returns the current processor tick count. The count starts at 0 when Siebel CRM starts running and increments the number of times per second according to operating system settings.

Format

Clib.clock()

Clib Character Classification Methods

This topic describes Clib character classification methods that the Clib object supports. It includes the following topics:

Overview of Clib Character Classification Methods

Siebel eScript does not include character types. For example, a char character is actually a string that is one character in length. Actual usage is similar to the C programming language. For example, the following Clib Is Alphanumeric method works properly:

var t = Clib.isalnum('a');



var s = 'a';

var t = Clib.isalnum(s);

This code displays the following output:

true

true

The Clib Is Alphanumeric method in the following example causes errors because the each argument to each statement is a string that contains more than one character:

var t = Clib.isalnum('ab');



var s = 'ab';

var t = Clib.isalnum(s);

A character classification method returns one of the following values:

True
False

Clib Is Alphabetic Method

The Clib Is Alphabetic method returns True if the value you specify in the char argument is one of the following values:

An alphabetic character from A through Z
An alphabetic character from a through z

If the value you specify is not one of the these values, then it returns Null.

Format

Clib.isalpha(char)

The following table describes the arguments for the Clib Is Alphabetic method.

Argument	Description
char	A single character or a variable that contains a single character.

Clib Is Alphanumeric Method

The Clib Is Alphanumeric method returns True if the value you specify in the char argument is one of the following values:

An alphabetic character from A through Z
An alphabetic character from a through z
A digit from 0 through 9

If the value you specify is not one of the these values, then it returns Null.

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.isalnum(char)

Clib Is ASCII Method

The Clib Is ASCII method returns True if the value you specify in the char argument is an ASCII code from 0 to 127. If the value you specify is not one of the these values, then it returns Null.

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.isascii(char)

Clib Is Control Method

The Clib Is Control method returns True if the value you specify in the char argument is a control character that an ASCII code from 0 through 31 represents. If the value you specify is not one of the these values, then it returns Null.

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.iscntrl(char)

Clib Is Digit Method

The Clib Is Digit method returns True if the value you specify in the char argument is a decimal digit from 0 through 9. If the value you specify is not one of the these values, then it returns Null.

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.isdigit(char)

Clib Is Lowercase Method

The Clib Is Lowercase method returns True if the value you specify in the char argument is a lowercase alphabetic character from a through z. If the value you specify is not one of the these values, then it returns Null.

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.islower(char)

Clib Is Printable Method

The Clib Is Printable method returns True if the value that you specify in the char argument is a printable character that you can enter from the keyboard and that an ASCII code 32 through 126 represents. If the value you specify is not one of the these values, then it returns Null.

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.isprint(char)

Clib Is Printable Not Space Method

The Clib Is Printable Not Space method returns True if the value you specify in the char argument is a printable character other than the space character that ASCII code 32 represents. If the value you specify is not one of the these values, then it returns Null.

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.isgraph(char)

Clib Is Punctuation Mark Method

The Clib Is Punctuation Mark method returns True if the value that you specify in the char argument is a punctuation mark that you can enter from the keyboard. If the value you specify is not one of these values, then it returns Null.

This method returns True if one of the following ASCII codes represents the punctuation mark:

33 through 47
58 through 63
91 through 96
123 through 126

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.ispunct(char)

Clib Is Space Method

The Clib Is Space method returns True if the value you specify in the char argument is a white space character. If the value you specify is not one of the these values, then it returns Null.

The following table describes the items for which the Clib Is Space method returns a value of true.

Description	ASCII Value
Horizontal tab	9
Newline	10
Vertical tab	11
Form feed	12
Carriage return	13
Space character	32

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

For more information, see Use White Space to Improve Readability.

Format

Clib.isspace(char)

Clib Is Uppercase Method

The Clib Is Uppercase method returns True if the value you specify in the char argument is an uppercase alphabetic character from A through Z. If the value you specify is not one of the these values, then it returns Null.

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.isupper(char)

Clib Is Hexadecimal Method

The Clib Is Hexadecimal method returns True if the value you specify in the char argument is a hexadecimal character. If the value you specify is not one of the these values, then it returns Null.

A hexadecimal character is one of the following:

A number from 0 through 9
An alphabetic character from a through f.
An alphabetic character from A through F.

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Format

Clib.isxdigit(char)

Clib Error Methods

This topic describes clib error methods. It includes the following topics:

Clib Clear Error Method

The Clib Clear Error method clears the error status and resets the end-of-file flag for a file that you specify. For usage information, see Overview of Clib File Input and Output Methods.

Format

Clib.clearerr(filePointer)

The following table describes the arguments for the Clib Clear Error method.

Argument	Description
filePointer	Identifies the file name.

Clib Get Error Number Method

The Clib Get Error Number method determines if an error has occurred in the buffer where Siebel eScript reads a file. It returns one of the following values:

If no error exists, then it returns the following value:
0
If an error exists, then it returns the error number.

Format

Clib.ferror(filePointer)

The arguments for this method are the same as the arguments for the Clib Clear Error method. For more information, see Clib Clear Error Method.

Clib Get Error Message Method

The Clib Get Error Message method returns the descriptive error message that is associated with the error number that the error number property identifies. When some methods fail to run properly they store a number in the error number property. This number corresponds to the type of error encountered. The Clib Get Error Message method converts this error number to a descriptive string and returns it.

Format

Clib.strerror(ToNumber(Clib.errno)

For more information, see Clib Error Number Property.

Clib Save Error Message In String Method

The Clib Save Error Message In String method is identical to the Clib Get Error Message except if you specify the errmsg argument, then the Save Error Message In String method saves the error message in this argument as a string.

Format

Clib.perror([errmsg])

The following table describes the arguments for the Save Error Message In String method.

Argument	Description
errmsg	An argument that contains the message that describes the error.

Clib Error Number Property

The Clib Error Number property stores an error number if a method fails to run correctly. Many methods in the Clib and Siebel library objects set errno to a nonzero value when an error occurs. Siebel eScript implements errno as a macro to the internal function errno. For more information, see Siebel Library Methods.

Format

Clib.errno

To return the error number stored in the Clib.errno property, you use the following ToNumber conversion method:

ToNumber(Clib.errno)

For more information, see Convert Value to Number Method.

You cannot use Siebel eScript code to modify the errno property. It is available only for read-only access.

You can configure Siebel CRM to reference the error message that is associated with a Clib error number. For more information, see Clib Get Error Message Method.

Other Clib Methods

This topic describes other Clib methods. It includes the following topics:

Clib Convert Character to ASCII Method

The Clib Convert Character to ASCII method clears every bit of the value that the char argument contains except for the seven least significant bits. The result is a seven-bit C representation of the character. It returns this value as a seven-bit ASCII representation.

If the value you specify in the char argument is already a seven-bit ASCII character, then it does not clear any bits and returns the character.

Format

Clib.toascii(char)

The arguments for this method are the same as the arguments for the Clib Is Alphabetic method. For more information, see Clib Is Alphabetic Method.

Example

The following example returns the close parenthesis character:

TheApplication().RaiseErrorText(Clib.toascii("©"));

For more information, see Clib Is ASCII Method.

Clib Modify Environment Variable Method

The Clib Modify Environment Variable method creates an environment variable, sets the value of an existing environment variable, or removes an environment variable. It returns one of the following values:

If it is successful, then it returns the following value:
0
If it is not successful, then it returns negative 1.

The Clib Modify Environment Variable method does the following:

Sets the environment variable that the varName argument identifies to the value that the stringValue argument contains.
Any modification that it makes to an environment variable persists only while the Siebel eScript code and any process that this code calls is running. After this code runs, the environment variable reverts to the value it contained before this method modified this value.
Automatically removes any environment variable it creates after it finishes.

Format

Clib.putenv(varName, stringValue)

The following table describes the arguments for the Clib Modify Environment Variable method.

Argument

Description

varName

The name of an environment variable, enclosed in quotes.

stringValue

The value that this method assigns to the environment variable, enclosed in quotes.

If the value in the stringValue argument is null, then this method removes the environment variable that the varName argument identifies.

Example

The following example creates an environment variable and assigns a value to it. To confirm that the variable was created, it then traces the return value:

TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");

var a = Clib.putenv("TEST","test value");

TheApplication().Trace("TEST        : " + a);

TheApplication().Trace("TEST= " + Clib.getenv("TEST");

TheApplication().TraceOff();

This example produces the following result:

03/05/04,16:56:28,START,7.5.3 [16157] LANG_INDEPENDENT,SADMIN,3388,7448

03/05/04,16:56:28,COMMENT,TEST        : 0

03/05/04,16:56:28,COMMENT,TEST= test value

03/05/04,16:56:28,STOP

Clib Get Environment Variable Method

The Get Environment Variable method returns the value of an environment variable.

Format

Clib.getenv(varName)

The following table describes the arguments for the Get Environment Variable method.

Argument	Description
varName	The name of an environment variable, enclosed in quotes.

Example

The following example returns the value of the PATH environment variable:

TheApplication().RaiseErrorText("PATH= " + Clib.getenv("PATH"));

Clib Send Command Method

The Clib Send Command method sends a command to the command processor for the operating system and opens an operating system window where it runs. After completing the command, it closes this window. It returns the value that the command processor returns. For an alternative that does not open a window, see Siebel Library Call DLL Method.

Format

Clib.system(commandString)

The following table describes the arguments for the Clib Send Command method.

Argument	Description
commandString	Contains the name of a valid operating system command. This value can include a formatted string followed by variables. For more information, see Format Characters for Methods That Print.

Example

The following example displays a directory in a DOS window:

Clib.system("dir /p C:\\Backup");

Clib Search Array Method

The Clib Search Array method searches an array for a value that you specify. It returns one of the following values:

If it finds the value you specify in the key argument, then it returns an array variable that matches the value you specify in the key argument.
If it does not find the value you specify in the key argument, then it returns the following value:
Null

It only searches through array elements that include a positive index. It ignores array elements that include a negative index.

Format

Clib.bsearch(key, arrayToSort,  [elementCount,]  compareFunction)

The following table describes the arguments for the Clib Search Array method.

Argument	Description
key	The value for which this method searches.
arrayToSort	The name of the array that this method searches.
elementCount	The number of array elements that this method searches. If you do not specify the elementCount argument, then it searches the entire array.
compareFunction	A custom function that can affect the sort order. The value for the compareFunction argument must include the following items: The key argument as the first argument A variable from the array as the second argument

Example

The following example uses Clib.qsort and Clib.bsearch to locate a name and related item in a list:

(general) (ListCompareFunction)

function ListCompareFunction(Item1, Item2)

{

   return Clib.strcmpi(Item1[0], Item2[0]);

}
(general) (DoListSearch)

function DoListSearch()

   // create array of names and favorite food 

   var list = 

   {

      {“Brent”, “salad”}, 

      {"Laura", "cheese" },

      { "Alby", "sugar" }, 

      { "Jonathan","pad thai" }, 

      { "Zaza", "grapefruit" }, 

      { "Jordan", "pizza" }

   }; 



   // sort the list

   Clib.qsort(list, ListCompareFunction);

   var Key = "brent";

   // search for the name Brent in the list 

   var Found = Clib.bsearch(Key, list, ListCompareFunction);

   // display name, or not found 

   if ( Found != null )

      TheApplication().RaiseErrorText(Clib.rsprintf

      ("%s's favorite food is %s\n", Found[0][0],Found[0][1]));

   else 

      TheApplication().RaiseErrorText("Can not find name in list."); 

}

Clib Sort Array Method

The Clib Sort Array method sorts elements in an array, starting with index 0, and then continuing to the value that you specify in the elementCount argument minus 1. This method differs from the Sort Array method in standard JavaScript in the following ways:

The Clib Sort Array method can sort a dynamically created array.
the Sort Array method in standard JavaScript works only with an array that an Array statement explicitly creates.

Format

Clib.qsort(array, [elementCount, ]compareFunction)

The following table describes the arguments for the Clib Sort Array method.

Argument

Description

array

The array that this method sorts.

elementCount

The number of elements in the array, up to 65,536.

If you do not specify the elementCount argument, then this method sorts the entire array.

compareFunction

A custom function that can affect the sort order.

Example

The following example prints a list of colors sorted in reverse alphabetical order, ignoring case:

// initialize an array of colors

var colors = { "yellow", "Blue", "GREEN", "purple", "RED", 

"BLACK", "white", "orange" }; 

// sort the list using qsort and our ColorSorter routine

Clib.qsort(colors,"ReverseColorSorter"); 

// display the sorted colors

for ( var i = 0; i <= getArrayLength(colors); i++ )

   Clib.puts(colors[i]);



function ReverseColorSorter(color1, color2)

// do a simple string that is not case-sensitive

// comparison, and reverse the results too 

{

   var CompareResult = Clib.stricmp(color1,color2)

   return( _CompareResult ); 

}

This example produces the following output:

yellow 

white 

RED

purple

orange

GREEN 

Blue

BLACK

For more information, see Sort Array Method.