JANOS Help System: [Commands] [Topics] [Tech Support] [Printable Manual] [Search]
Built-In Functions Scripting DESCRIPTION Functions perform operations on a set of parameters and potentially return a result. A function is usually created when the task it performs will be required at various different points during a script. It is a write-once use-often kind of a programming feature. Some functions perform a task so common that they are needed in script after script. These are the kind of functions where it is useful to maintain in a library. JANOS scripting does support the include statement which permits you to create a PHP file with such functions and to simply include that file with each script. To support many of the very common functions JANOS scripting provides a Buit-In Function library. As scripting has been modelled after public PHP many of the common PHP functions can be found in the JANOS library as well as some that are very custom. These built-in functions eliminate the need to maintain a separate library of useful functions. These are also implemented at a native level and therfore operate much more efficiently that with compile bytecode. The Built-In Library supplies functions support a number of programming categories from string and array operations to system and Registry access. RENDERING AND OUTPUT The following functions generate output. When the script is referenced by the WebServer this output becomes part of the HTML stream. When the script is used in the command line batch file the output is then interpreted as a command line entry. In program execution this is simply just output. int print ( mixed $var ) Outputs the $var as a string. It is the functional equivalent of the ECHO statement. This always returns 1. int puts ( mixed $var ) Outputs the $var as a string followed by the "\r\n" sequence. In addition to generating a newline for formatting general output this appends the ENTER termination needed for command execution in batch use. This always returns 1. string printf ( string $format [, mixed $param ] ) Outputs the formatted string defined by $format. This uses the Standard C Library format specifiers. A variable number of $param values may be supplied. The formatted string is also returned. The sprintf() function is available for formatting a string. void header(string hdrline) Adds the supplied $hdrline to HTTP response headers when rendering HTML through the WebServer. var_dump ( var1 [ , var2 [ , ... ] ] ) Outputs a useful description of each variable. If var_dump() is issued without a parameter it will dump ALL of the local variables excluding the predefined arrays. STRING OPERATIONS The following functions perform operations on string variables. string ltrim( string $str [, string $character_mask ] ) Strip whitespace (or other characters) from the beginning of a string. string rtrim( string $str [, string $character_mask ] ) Strip whitespace (or other characters) from the end of a string. string trim( string $str [, string $character_mask ] ) Strip whitespace (or other characters) from both the beginning and end of a string. int strlen( string $string ) Returns the length of the given string. string strtolower( string $str ) Returns string with all alphabetic characters converted to lowercase. string strtoupper( string $str ) Returns string with all alphabetic characters converted to uppercase. string ucfirst( string $str ) Returns string with the first character of the first word converted to uppercase. string ucwords( string $str ) Returns string with the first character of each word converted to uppercase. string strval (expr) Returns a string representation for the value of the expression or variable. string substr ( string $str, int $start [, int $length] ) Returns a portion of the string specified by the start and length parameters. int strpos ( string $haystack, string $needle [, int $start] ) Returns the position in $haystack of $needle if the string occurs at or after $start. Returns -1 otherwise. int stripos ( string $haystack, string $needle [, int $start] ) Returns the position in $haystack of $needle if the string occurs at or after $start. Returns -1 otherwise. The comparison is case-independent. int strrpos ( string $haystack, string $needle [, int $start] ) Returns the last position in $haystack of $needle if the string occurs at or after $start. Returns -1 otherwise. int strripos ( string $haystack, string $needle [, int $start] ) Returns last the position in $haystack of $needle if the string occurs at or after $start. Returns -1 otherwise. The comparison is case-independent. bool startsWith( string $haystack, string $needle ) Returns TRUE if $haystack starts with the string $needle. bool endsWith( string $haystack, string $needle ) Returns TRUE if $haystack ends with the string $needle. int strcmp( string $str1, string $str2 ) Compares two strings in a binary safe manner. Returns 0 if both strings are equal. Returns a negative value (<0) if str1 less than str2 and a positive value (>0) if str1 is greater than str2. string bin2hex ( mixed $var ) Returns a String containing the hexadecimal representation of each character in $var. $var is converted to its string representation if not initially a String. string hex2bin ( string $hex ) Returns a string where the 2-byte hexadecimal representation of each character is supplied. Returns NULL is an the hexadecimal string contains an odd number of characters or any character not in the valid hexadecimal set [0-9a-fA-F]. string sprintf ( string $format [, mixed $param ] ) Returns a formatted string as defined by $format. This uses the Standard C Library format specifiers. A variable number of $param values may be supplied. string crc ( string $message ) Returns a string of length 8 containing the hexadecimal CRC32 checksum calculated for the contents of $message. string md4 ( string $message ) Returns a string of length 32 containing the hexadecimal MD4 message digest calculated for the contents of $message. string md5 ( string $message ) Returns a string of length 32 containing the hexadecimal MD5 message digest calculated for the contents of $message. string sha1 ( string $message ) Returns a string of length 40 containing the hexadecimal SHA1 message digest calculated for the contents of $message. string sha2 ( string $message ) Returns a string of length 64 containing the hexadecimal SHA256 message digest calculated for the contents of $message. ARRAY OPERATIONS There are a couple of functions supporting array variables specifically. int count( variable [, recursive] ) Returns the count of elements in an array or other variable. Includes recursive counts for multi-dimensional arrays if the recursive option is set to 1. array array_remove( array $arr, string $key ) Returns a copy of the array $arr without an element with the specified $key. DATA CONVERSION int intval ( mixed $var ) Returns an integer value for the variable. Returns null if a string cannot be interpreted as a number. double floatval ( mixed $var ) Alias for doubleval(). double doubleval ( mixed $var ) Returns a double value for the variable. Returns null if a string cannot be interpreted as a number. mixed unpack ( string $str, int $offset, int $length [, boolean $float ] ) This function is used to extract data packed into the string (binary byte array) $str. Values are assumed to be packed in big-endian order beginning at the provided $offset. The size of the parameter is defined by $length. The optional boolean $float is FALSE by default and if set to TRUE indicates that data is stored in IEEE 754 floating point format. With $float set to FALSE this returns an INTEGER whose value is stored starting at $offset in $str for $length bytes. This will retrieve a byte value ($length = 1), a short value ($length = 2) or an int ($length = 4). 64-bit values cannot be directly retrieved as there is no 64-bit PHP integer variable type. Values less than 4 bytes in length are unsigned. With $float set to TRUE this returns a DOUBLE whose value is stored in IEEE 754 format at $offset in $str for $length bytes. This retrieves a float value (length = 4) or a double value (length = 8). A NULL value is returned for any invalid combination of $length and $float. A NULL value is also returned for any attempted out of bounds string (array) reference. mixed endian ( mixed $var ) Reverses the endian order of a numeric value. This returns a variable of the same type and affects only numeric values. string urlencode ( mixed $var ) Encodes any non-alpha characters no tin the set [-_a-zA-Z] using %## encoding. Plus symbols ('+') replace space characters. string urldecode ( mixed $var ) Decodes any %## encoding in the given string. Plus symbols '+' are decoded to a space character. string base64_decode( mixed $var ) Decodes Base64 encoded string. string base64_encode( mixed $var ) Encodes string in Base64. DATE AND TIME int time ( void ) Returns the current time in seconds since midnight Jan, 1 1970 UTC. Same as getutc() . int getutc ( void ) Returns the current time in seconds since midnight Jan, 1 1970 UTC. Same as time() . string date ( string $format, [ int time ] ) Returns a string formatted according to the given format using the specified timestamp or the current time if no timestamp is provided. If omitted the timestamp would be the value of time() . A partial set of PHP-like formatting specifiers are supported. Either UTC or Local Time may be represented depending on the occurrence of 'U' or 'L' in the format string. Local Time is the default. Daylight Saving Time (DST) is applied if appropriate for the local timezone. Day d Day of the month, 2 digits with leading zeros (01-31) D A textual representation of the day, 3 letters (Mon-Sun) j Day of the month without leading zeros (1-31) Month m Numeric representation of the month, with leading zeros (01-12) M A short textual representation of a month, 3letters (Jan-Dec) n Numeric representation of a month, without leading zeros (1-12) Year Y A full numeric representation of a year, 4 digits y A two digit representation of a year Time a Lowercase Ante meridiem or Post meridiem (am or pm) A Uppercase Ante meridiem or Post meridiem (AM or PM) g 12-hour format of an hour without leading zeros (1-12) G 24-hour format of an hour without leading zeros (0-23) h 12-hour format of an hour with leading zeros (01-12) H 24-hour format of an hour with leading zeros (00-23) i Minutes with leading zeros (00-59) s Seconds with leading zeros (00-59) Timezone U Represent Universal Coordinated Time (UTC) L Represent Local Time (default) e Timezone identifier, same as 'T' (EST or UTC) T Timezone abbreviation (EST or UTC) string gmtime ( [ int time ] ) Formats a time value as a string. If the parameter is omitted the current time is formatted. The time value is in seconds since midnight Jan, 1 1970 UTC. The resulting string is formatted, for example, as: "Thu, 19 Nov 2015 13:13:12 EST". This is the same as: date("D, d M Y H:i:s T"). FILE OPERATIONS int filesize(string $filename) Returns the length of the file in bytes. int filemtime ( string $filename ) This function returns the timestamp when the content of the file was last changed. This is the number of seconds since midnight Jan 1, 1970 in UTC. bool file_exists(string $filename) Returns TRUE if the file/directory referenced by the supplied specification exists and FALSE otherwise. bool is_file(string $filename) Returns TRUE if the file referenced by the supplied specification exists and is not a folder. bool unlink(string $filename) Deletes the specified file. Returns TRUE if successful. int fopen(string $filename, string $flags) Opens a file for reading, writing, etc. The $flags parameter defines the mode of access following the Standard C Liobrary conventions. For reading a file would typically be opened using the flag string "rb". For writing the string "wb" would be appropriate. int fread(int $handle [, int $length] ) Returns a string containing up to $length bytes from the file. If $length is omitted the entire content of the file will be read. int fread(string $filename) Returns a string containing the entire content of the file defined by the supplied specification. int fwrite(int $handle, $string [, int $length] ) Writes the content of $string to the associated file. If specified, a maximum of $length bytes will be written. Returns the number of bytes written or FALSE on error. int fwrite(string $filename, $string) Creates the file defined by teh supplied specification containing the content of $string. bool feof(int $handle) Returns TRUE if the file has reached the end-of-file. int fclose(int $handle) Closes the file resource. It is good practice to close files that have been opened for reading or writing. There are only a limited number of available file handles. String getcwd( ) Returns the current working directory. bool chdir(string $directory) Change working directory. Returns FALSE if the new specification does not result in an existing folder. array scandir(string $directory) Return an array of files and folders from the referenced directory. bool is_dir(string $directory) Returns TRUE if the directory referenced by the supplied specification exists and is not a file. bool mkdir(string $directory) Creates the specified folder if it does not exist. Returns TRUE if successful. bool rmdir(string $directory) Removes the specified folder if it does not exist. Returns TRUE if successful. string file_crc ( string $filename ) Returns a string of length 8 containing the hexadecimal CRC32 checksum calculated for the contents of the file. string file_md4 ( string $filename ) Returns a string of length 32 containing the hexadecimal MD4 message digest calculated for the contents of the file. string file_md5 ( string $filename ) Returns a string of length 32 containing the hexadecimal MD5 message digest calculated for the contents of the file. string file_sha1 ( string $filename ) Returns a string of length 40 containing the hexadecimal SHA1 message digest calculated for the contents of the file. string file_sha2 ( string $filename ) Returns a string of length 64 containing the hexadecimal SHA256 message digest calculated for the contents of the file. JSON SUPPORT Support for JSON (JavaScript Object Notation - json.org ) is provided. JSON is used in many different ways. It is also a good means of preserving a PHP array structure in file storage and in thereby implementing a rudimentary database. array json_decode( string $json ) Returns an array structure for the JSON object supplied in JSON string representation. string json_encode( array $json ) Returns the JSON string representation of an array object. array json_load( string $filename ) Returns an array structure representing the JSON object stored in the referenced file. The file contains the string representation of the JSON object. boolean json_save( string $filename, array $json ) Stores an array structure representing a JSON object in the referenced file. The file will contain the string representation of the JSON object. Returns TRUE when the write is successful. LANGUAGE SUPPORT There are functions provided that ascertain the status of a variable. bool is_null( mixed $var ) Tests if a variable is NULL. Returns True or False . bool is_bool( mixed $var ) Tests if a variable is Boolean. Returns True or False . bool is_int ( mixed $var ) Tests if a variable is an Integer. Returns True or False . bool is_double ( mixed $var ) Tests if a variable is a Double. We store all floating point values as Double. Returns True or False . bool is_string ( mixed $var ) Tests if a variable is a string. Returns True or False . bool is_array ( mixed $var ) Tests if a variable is an array. Returns True or False . bool isset ( mixed $var ) Returns TRUE is the variable has been assigned a value. bool empty ( mixed $var ) Determine whether a variable is considered to be empty. A variable is considered empty if it does not exist or if its value equals FALSE. This is equivalent to: isset($var) || $var == false. REGISTRY ACCESS The Registry stores name-value data typically for configuration. A script may need access to defined settings or be able to preserve settings of its own. These function access the JANOS Registry system. string getRegistryString(string $key [, string $default]) Gets the content of the supplied Registry key. Note that this returns an empty string if the key has not been defined. Note also that an empty string is considered to be a FALSE boolean so the returned string can be used in a conditional statement. bool getRegistryBoolean(string $key [, boolean $dflt]) Returns the boolean equivalent of the Registry key value. bool setRegistryString(string $key, string $value) Sets the content of the supplied Registry key. The key is deleted if the supplied value is an empty string. string[] getRegistryList(string $node [, $children = False]) Returns and array of fully qualified keys for entries (children = False) or child nodes (children = True) within the specified node. SYSTEM FUNCTIONS void syslog ( string $message ) Enters the message in the system log jniorsys.log file. void flush ( void ) Flushes buffers and attempts to send any output generated to the browser or console. void sleep ( int $milliseconds ) Flushes buffers and sleeps the process for the defined number of milli- seconds. If a script must wait for an external event it is important to allow the processor to perform other tasks. void yield ( void ) Yields the process. This should be used by extremely lengthy procedures to reduce the load on the processor and avoid watchdog timeouts. REGULAR EXPRESSIONS Regular Expressions (REGEX) define string search patterns. JANOS scripting can utilize these. int ereg ( string $pattern, string $substring [, array $regs] ) Returns the position in $substring of a match with $pattern. Returns FALSE otherwise. If $regs is supplied on a match it is set as an array whose first element is the matched string. int eregi ( string $pattern, string $substring [, array $regs] ) Returns the position in $substring of a match with $pattern. Returns FALSE otherwise. If $regs is supplied on a match it is set as an array whose first element is the matched string. Case-independent comparisons are performed. array split( string $pattern, string $substring [, int $limit] ) Returns an array of string tokens from $substring using matches to $pattern as the separators. If $limit is provided the returned array will be limited to that number of entries where the last entry will contain the balance of the original string. array spliti ( string $pattern, string $substring [, int $limit] ) Returns an array of string tokens from $substring using matches to $pattern as the separators. If $limit is provided the returned array will be limited to that number of entries where the last entry will contain the balance of the original string. Comparisons are case-independent. string ereg_replace ( string $pattern, string $replacement, string $substring ) Replaces all matches to $pattern in $substring with the string $replacement. Returns FALSE on error. Returns the original string if no matches are found. string eregi_replace ( string $pattern, string $replacement, string $substring ) Replaces all matches to $pattern in $substring with the string $replacement. Returns FALSE on error. Returns the original string if no matches are found. Comparisons are case-independent. [/flash/manpages/program.hlp:697]