Optimize - Perform Multidimensional Optimization
| optimum = Optimize ( tag ... ) |
| optimum | The optimum result. | |
| tag | Any of the tagged arguments below. |
| Enum::list | A list of points on a dimension. More than one Enum argument may be specified. | |
| Maximum::point | A point (usually an intersection or module) to be maximized. | |
| Minimum::point | A point (usually an intersection or module) to be minimized. |
This module enumerates through all combinations of the given Enum points and returns either the maximum or minimum value that can be calculated from the points. The result of the module is the min/max number. The context is also updated with the Enum points corresponding to that min/max result.
| Optimize(Enum::Inventory.. Enum::UDate:1/1/02..12/31/02 Maximum::[Sales]) | determines the item having the greatest sale on a given day. The sale amount is returned while Item* and UDate* reflect the item and date for the largest sale |
The next example determines the nine digit number with some special properties. None of the digits may be zero. The first digit of the number must be divisible by one, the first two digits must be divisible by two, the first three by three all the way up to the entire 9 digit number which must be divisible by 9. Finally, each digit from 1 to 9 must be used, none may repeat.
Example 35 - Using Optimize Module to Determine Magic 9 Digit Number
|
Dim A,B,C,D,E,F,G,H,I Int Range Multiple [Test Alpha..] Enum(Int:2..9 If::{MthMod(Int:=Str(Alpha* Head::Int*) Int*) <> 0} Then::Logical:False), Enum(Int:1..8 If::Str(Str(Alpha* Tail::{9 - Int*}) Has::Str(Alpha* Begin::Int* Length::1)) Then::Logical:False), Logical:True Context Add E:5 /*the 5th digit must be 5 to be divisible by 5 */ Eval Optimize(Enum::A:1,3,7,9 Enum::B:2,4,6,8 Enum::C:1,3,7,9 Enum::D:2,4,6,8 Enum::F:2,4,6,8 Enum::G:1,3,7,9 Enum::H:2,4,6,8 Enum::I:1,3,7,9 Maximum::[Test Str(A* B* C* D* E* F* G* H* I*)]) = Str(A* B* C* D* E* F* G* H* I*) |
Or - Logical Or
| logres = Or ( arg arg ... ) |
| logres | The logical Or'ing of its arguments. | |
| arg | One or more points evaluated as logicals. |
The Or module returns the logical or of its arguments. If any of the arguments are lists then the points of that list are logically or'd. Normally all arguments are evaluated before testing. If there is a higher probability of one argument being true then place that argument before the others and quote the remaining arguments. V4 will then evaluate arguments until it finds one that evaluates to true. The Or module will immediately return true without evaluating the remaining arguments. If the module is called with no arguments it returns Logical:False.
| Or(Logical:True Logical:False) | Logical:True | |
| Or(1 @[ExpensiveToCalc]) | Logical:True without evaluating the second argument. |
OSExt - Link/Call an External Operating System Module
| ospt = OSExt ( Dim:osdim targarg ... Dim:result Dim:arg1 Dim:arg2 ... ) | |
| modres = OSExt ( OSExt( ospt arg1 arg2 ... ) |
| ospt | A point describing an external module. | |
| osdim | A dimension of type OSHandle | |
| tagarg | Optional tagged arguments. | |
| result | The dimension to be used for results returned by calls to the external module. | |
| arg | The dimensions to be used for each of the arguments to the external module. |
| Library::name | A string reference naming the dynamic link library containing the external module. | |
| Module::name | The name of the external module. |
| Error? | Generates a memory exception error (used primarily for testing). |
The OSExt module is used to link to and invoke externally written and compiled modules. This permits the users to customize V4 with modules developed in any of the Windows supported languages. Usage of this module requires two steps. The first is to create a point on an OS dimension which refers to a specific external module. The second step is to call the module with the necessary arguments. V4 handles all data conversions both in calling the external module and with the returned result.
|
Dim Mod OS Context Add OSExt(Dim:OS Library::mylibrary.dll Module::MyModule Dim:Money Dim:Int Dim:Num) |
| OSExt(Mod* 123 456) | The second argument is converted to a real and the result is Money:4493.98 |
OSFile - Information/Action on Operating System File(s)
| result = OSFile ( filespec Tag ) | |
| fullpathname = OSFile ( filespec ) |
| result | The result is based on the tag argument. | |
| filespec | A file specification which may include, depending on the following arguments, wild cards. | |
| fullpathname | If this module is called with a single argument then it parses that argument as a file name and returns the full system path name to that file. | |
| tag | One or more of the tagged arguments below. |
| Bytes::range | When used with the ListOf?, restricts the results to only those files of size within range. If range is a single number then only files matching that exact size are selected. Note that subdirectories are not checked for size. | |
| Copy::newfile | Copy the file filespec to the destination file newfile. If a file already exists as newfile then it will be overwritten. A string message confirming the copy is returned on success, otherwise the module fails. | |
| Dim::dim | Return the result as a point on the dim dimension. This is used in conjunction with the ListOf? option. | |
| Directory::option | Performs various tests/actions on directories: CREATE to create the specified directory (error if already exists), CREATEIF to create the directory (no error if exists), EXISTS to return TRUE if the first argument is an existing directory or FALSE if not a directory or nonexistant, REMOVE to remove the empty directory. | |
| Filter::isct | This argument is used in conjunction with the ListOf? option when returning a list of lines within a text file. V4 inserts the current line into the context (as a Dim:Alpha point or the dimension specified via the Dim argument) and evaluates isct for each line within the file. If the result of the evaluation is Logical:True then the line is taken as-is. If the result is Logical:False then the line is skipped and V4 continues with the next line of the file. If the result is an alpha string then that string is taken as the current line. If the result is a list then V4 returns each element of the list as if each element were a line within the file. If the result is UV4:None then immediately force an end-of-file for the file (i.e. no more lines are read from the file). | |
| Hash::mode | Hashes the contents of filespec based on the hash mode. The supported modes are: 32 to return a 32 bit (Dim:Int) hash value, 64 to return a 64 bit (Dim:Int2) hash value, CRC to return a 32 bit cyclic redundancy check code, MD5 to return the MD5 checksum. The result is returned as a 32-byte string. SHA256 to return the SHA-256 hash as a 64-byte hex string. SHA1 to return the SHA-1 hash. | |
| IC::logical | If the parameter is TRUE (default) then the 'case' of the file name is considered to be entirely lower case. If the parameter is FALSE then the case is kept as-is. | |
| ListOf::listtype | If listtype is FILES then a list of files matching the file specification pattern of the first argument is returned. If listtype is CONTENTS then a list of the contents of the file specified by the first argument is returned. Note that CONTENTS only returns a meaningful list when the file is text. This option may also be used with the Filter option. The list elements are normally points on Dim:Alpha but may be overridden with the Dim option. | |
| Move::tofile | Moves the source file to tofile. If the tofile already exists then the module fails. The three-colon option can be used with this tag to force an overwrite if the toFile already exists. An Dim:Alpha confirmation message is returned if the move is successful. | |
| Num::lines | Specifies the number of lines to verify with the Table option. If lines is 0 (zero) then the modules fails with the first error detected or returns a 0 if no errors are detected. If lines is greater than 0 then only the first lines lines of the file are scanned for errors. | |
| Rename::tofile | Renames filespec to tofile. The target name (tofile) must not already exist. A string message confirming the rename is returned on success, otherwise the module fails. | |
| Table::name | Attempts to parse the contents of filespec according to the columns in the V4 table name. The value returned is the integer number of errors detected, zero meaning that no errors were detected. (See the Num tag for other options.) Note that no macro processing occurs within this module. | |
| Update::dtrange | When used with the ListOf?, restricts the results to only those files updated within dtrange. If dtrange is a specific date-time then only files with that exact date-time are selected. If dtrange is none then no date-time selection is performed. Note that subdirectories are not checked for update date-time selection. | |
| Width::chars | Specifies the maximum number of characters in a line when reading files via the ListOf option. The default is around 32000 characters so this option is only needed when processing files with extremely long lines. |
| Access? | Returns the access date and time for filespec. | |
| Bytes? | Returns the file size in bytes of filespec as a point on Dim:Num. | |
| Delete? | Delete the file referenced by filespec. A string message confirming the deletion is returned if the file is actually deleted, otherwise the module fails. | |
| Directory? | Returns Logical:True if filespec refers to a directory, Logical:False otherwise. | |
| Exists? | Return Logical:True if the filespec refers to an existing file, Logical:False otherwise. | |
| Extension? | Returns the extension portion of filespec. | |
| FileName? | Returns the file name and extension. | |
| FullPathName? | Returns the full path name of filespec. | |
| Hidden? | Normally the ListOf? option does not return hidden files. Hidden files may be returned by specifying this option with ListOf?. | |
| ListOf? | This option either returns a list of all lines within a file or it returns a list of files as specified by filespec. If filespec contains wild characters then a list of files is returned. If no wild characters are contained in filespec then a list of the lines within the file are returned. See the ListOf tagged argument as this is just an automatic version. | |
| Name? | Returns only the name portion of filespec (no device, directory, or extension). | |
| Nest? | Used in conjunction with ListOf? to include all nested directories. If this tag is not specified, directories are return in the list of files. If this tag is specified then the directories are not included but all files within the directories are. | |
| Path? | Returns the device and directory path of filespec. | |
| Update? | Returns the date-time the filespec was last updated. |
The OSFile module performs various functions pertaining to operating system files
V4 will read text files of various shapes and sizes. If a byte-order-mark (BOM) is present at the beginning of a file then it will determine the format of the remainder of the file. V4 attempts to read text files on a line-by-line basis. If a line exceeds the maximum then V4 will read up to the maximum and then read the remainder as the 'next line'. This may cause unexpected results so it is advised to use the Width option to increase the maximum line width if it may exceed 32000 characters.
Each line of a text file is returned as a V4 point. A line within a text file may exceed the maximum number of characters allowed in a V4 point. When this occurs, the text file line is broken into multiple sections where each section adheres to the V4 point maximum. Text lines are broken on white-spaces.
| OSFile("*.v4" ListOf?) | results in a list of all files with a 'v4' extension | |
| OSFile("*.v4" ListOf? Bytes::Int:<25000) | results in a list of all 'v4' files less than 25000 bytes | |
| Enum(OSFile("*.v4" ListOf? Dim:F) | Lists all 'v4' files giving the filename, size, and update date-time |
|
@EchoT(OSFile(F* Name?) OSFile(F* Bytes?) OSFile(F* Update?))) |
| Sort(OSFile("*.v4" ListOf? Dim:F) Reverse::OSFile(F* Bytes?) | Same as above except listing is largest to smallest |
|
Do::EchoT(OSFile(F* Name?) OSFile(F* Bytes?) OSFile(F* Update?) Enum(OSFile("*.tmp" Update::MakeP(Dim:UDT Special::NID:LT {UDT:{now} - (12 * 60 * 60)}) ListOf?) |
| @OSFile(Alpha* Delete?)) | Deletes *.tmp files creating before 12 hours ago |
The example below compares the update date-times of a list of files between two directories and updates the second directory if the file is not as recent or missing.
Example 36 - File Synchronization Between Directories
|
[FileDTCompare Target.. FileSpec..] Do(Enum(OSFile(FileSpec* Dim:File ListOf?) @If({OSFile(File* Update?) <> OSFile(Str(Target* OSFile(File* Name?) "." OSFile(File* Extension?)) Update?),0} Then::Spawn(Str("cmd /C copy " File* " " Str(Target* OSFile(File* Name?) "." OSFile(File* Extension?)))))) ) |
| [FileDTCompare FileSpec:"*.v4a" Target:"\V4Release\"] | Compares all *.v4a files in current directory with those in the V4Release directory, updating those that are not current |
OSInfo - Return Operating System Information
| info = OSInfo ( tagarg ) |
| info | The information point returned by the module | |
| tagarg | One or more of the tagged arguments described below |
| CommandLine::mode | If mode is ALL then returns all components of the command line used to invoke this process as a list. | |
| Directory::dirname | Sets the process working directory to dirname. This option returns the old working directory as its value. | |
| Environment::variable | Returns the value of the process environment variable. | |
| IPAddress::mode | Returns all IP addresses of the current machine as a list. The mode may be V4 for the IPV4 address or V6 for the IPV6 address. | |
| ListOf::item | Returns a list as specified by item. If item is VOLUMES then a list of volume names (on Dim:Alpha) is returned. If item is ENVIRONMENT then a list of environment variables is returned. | |
| Volume::name | Specifies the name of a disk volume to be referenced with subsequent tagged arguments. |
| Bits? | Returns the number of bits (32/64) of the processor. | |
| Bytes? | Returns a list giving total and available space on a specified device (volume). A Volume must precede this tag. The format of the returned list is (size free available) where size is the total size of the volume, free is the total free space on the volume, and available is the total space available to the calling process (if quotas are enabled). Note that all values are specified as points on Dim:Num and reflect megabytes, not bytes. A value of -1 indicates an unknown value. | |
| ComFileExt? | Returns the preferred command file extension for th current operating system. | |
| CommandLine? | Returns all components of the command line following the entry specifying the currently running V4 program. The module fails if no components were specified after the V4 program name. | |
| CPU? | Returns the type of CPU running V4. | |
| Directory? | Returns the working directory of the current V4 process. | |
| Endian? | Returns either NId:Little or NId:Big depending on the processor. | |
| Environment? | Returns a list of all currently defined process environment variables. | |
| Id? | Returns the volume id, if known, of the previously specified Volume. | |
| Id? | Returns the process id number of the current running V4 process (if no volume previously given). | |
| IPAddress? | Returns the primary IPV4 IP address of the current machine (as referenced by gethostname()/gethostbyname(). The result is returned as a string point on Dim:Alpha. | |
| Name? | Returns the current host system name (if no volume previously specified). | |
| Name? | Returns the volume name of the previously specified Volume. | |
| OS? | Returns the name of the current operating system. | |
| Processors? | Returns the number of processors available on the current system. Note that Intel hyperthreaded CPUs will return 2! | |
| Type? | Returns, as a point on Dim:UV4, the type of volume previously given as a Volume argument. The current possible return values are UV4:Removable for removable drives (ex: floppy, memory stick, etc.), UV4:Fixed for fixed drives, UV4:Network for network drives, UV4:CDRom for CD/DVD drives, and UV4:RamDisk for solid-state drives. If the drive type is not known then UV4:Unknown(hex:nnn) is returned where nnn is an operating system dependent drive-type code. | |
| User? | Returns the login name of the user running the current V4 process. | |
| Volume? | Returns a list of all volumes/drives on the current system (same as ListOf:Volumes). |
This module returns information regarding the current operating system.
| OSInfo(Name?) | returns Alpha:"WINNT" if V4 running under NT | |
| Enum(OSInfo(Environment?) @Echo(Alpha* " = " OSInfo(Environment::Alpha*))) | Outputs all environment variables and values | |
| OSInfo(IPAddress?) | returns current machine's ip-address as a string |
Output - Redirects Stream Output to Different Files or Devices
| result = Output ( tagarg ) |
| result | The result of this module is always Logical:True. | |
| tagarg | One or more of the tagged arguments below. |
| Append::file | Open an existing file (or create if it does not exist) and position to the end-of-file. | |
| Binding::qisct | Declare an intersection to be bound to the text flowing into the stream. When the stream is closed all text associated with the stream is saved as a BigText point and that point is bound as the value of qisct. The parameter should be quoted if it is a literal binding. Note that the binding occurs when the stream is closed, not with this module call. If the isct contains any context references (i.e. dim:*) then those references are with respect to the stream close context. Note also that BigText points can hold approximately 32,000 characters of text. If a stream exceeds the maximum, a module failure will occur. | |
| Close::stream | Close the file associated with stream and reassign stream to the process' stdout. | |
| Create::file | Create a new file. The module returns the name of this file as its value. | |
| Encode::mode | Defines the output encoding of the stream. The values are ASCII (default) for ASCII encoding, UTF8 for UTF-8 encoding, UTF8nh for UTF-8/no-header encoding (i.e. no byte order mark at the begining of the file), UTF16 for UTF-16 environment dependent encoding, UTF16le for UTF-16/little-endian encoding and UTF16be for UTF-16/big-endian encoding. | |
| Get::chars | Returns a string consisting of the next chars characters of the specified stream rounded down to a full line. For instance if the output stream contains 100 lines each 50 characters in length then Output(Id::xxx Get::125) will return the first two lines. If chars is smaller than the number of characters in the next line then an empty string is returned. The stream must have been initialized as a buffered stream. The returned characters/lines are removed from the output buffer. | |
| IC::logical | If logical is TRUE (default) then the filename is considered case-insensitive and converted to all lower case. If logical is FALSE then the case of the output file is maintained. | |
| Id::name | Associate the name with the file being created or appended-to. This name may be used in subsequent Output calls or in any of the echo modules (e.g. Echo or EchoS). | |
| Length::option | If option is Lines then the number of lines output to the stream is returned. If it is Characters then the number of characters output is returned. | |
| To::stream | Associate the previously specified file to the data stream. The defined V4 streams are Data, Debug, Error, Progress, Prompt, Status, Trace, and Warn. |
| Buffer? | Create a new stream that buffers internally, i.e. all output to the stream will be stored in the V4 process space. | |
| Close? | Close the previously specified file Id or To stream. The name of the just closed file is returned as the result. | |
| Count? | Returns the number of lines output to the file named by an Id or To stream. | |
| Data? | Return the filename associated with the current data stream as a point on the Dim:Alpha dimension. | |
| FileName? | Returns the file name of the file associated with the prior Id or To argument. If no prior argument is given then this returns the path name of the current data stream (same as Data?). The result is a point on Dim:Alpha. The name returned is the name used to create the file, use OSFile(FullPathName?) to obtain the full path name. | |
| Length? | Returns the number of characters output to the stream. |
This module is used to assign files or devices to any of the V4 data streams. Each data stream is initially assigned to the process' stdout. Each stream must be assigned to an output at all times. If a stream is assigned to a file and that file is closed then V4 automatically reassigns the stream back to the process' stdout.
Multiple files may be opened with this module. A file need not be assigned to a stream. It is possible to create multiple files and alternate them within a stream.
The Close? option may be used to close any stream. A normal V4 exit will automatically close all currently open streams.
V4 defines seven streams. The Data stream is the output stream for the Echo modules. The Debug stream is used for all debugging output from the EchoD module. The Error stream is used to output all V4 errors. The Progress stream is used for all the progress messages that are trigged by the 'Set Trace Progress' command. The Prompt stream is used to output all V4 prompts. The Status stream is used for status messages such as the processing recap when V4 exits. The Trace stream is for all trace output, again controlled by the 'Set Trace' command, but excluding progress output. The Warn stream is for all V4 warnings.
V4 defines three Id names. 'StdOut' represents the process' stdout, 'Console' represents the process's console (if distinct from stdout), 'None' represents the null file or device.
| Output(Create::"foo.txt" To::Data) | Directs all Data stream output to the file foo.txt | |
| Output(Data?) | returns Alpha:"foo.txt" assuming Output above | |
| Output(Append::"v4performance.txt" To::Status) | Directs the final V4 processing summary to the file | |
| Output(Create::"otherfile.txt" Id::Other) | Creates a new file and assigns it an id of Other. | |
| Echo(Out::Other xxx) | Echo xxx to otherfile.txt (from above example) | |
| Output(Id::Other Close?) | Close the file (otherfile.txt) associated with Id::Other | |
| Spawn("cmd /C " Output(Id:cmd Close?)) | Close the file and execute it as a subprocess | |
| Output(Binding::@[SaveStream] Id::SS) | All output via Id SS will be saved as a BigText point bound to [SaveStream] |