17 July 1996 IT Solutions Control DLL Page 1 User's Manual for the IT Solutions Control DLL (ITSCTRL) Version 2.0 by James Gray Walker "IT Solutions" GmbH 0. Table of Contents 0. Table of Contents . . . . . . . . . . . . . . . . . . . . . 1 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Components . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.1. ITSCTRL.DLL . . . . . . . . . . . . . . . . . . . . . . 2 2.2. Control INI File . . . . . . . . . . . . . . . . . . . 3 2.3. Input Data File . . . . . . . . . . . . . . . . . . . . 3 2.4. GAWKDLL Processing Module . . . . . . . . . . . . . . . 3 2.5. Intermediate Data Files . . . . . . . . . . . . . . . . 3 2.6. E-Mail Software . . . . . . . . . . . . . . . . . . . . 3 3. ITSCTRL Invocation . . . . . . . . . . . . . . . . . . . . . 3 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 3 3.2. Creating the Input File . . . . . . . . . . . . . . . . 4 3.3. Loading ITSCTRL and Locating the Entry Point . . . . . 4 3.4. Calling the Entry Point . . . . . . . . . . . . . . . . 4 4. ITSCTRL Execution . . . . . . . . . . . . . . . . . . . . . 4 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 4 4.2. Capture of the Input File . . . . . . . . . . . . . . . 4 4.3. Update of the Job Sequence Number . . . . . . . . . . . 5 4.4. Stage Execution . . . . . . . . . . . . . . . . . . . . 5 4.5. ITSCTRL Return Code . . . . . . . . . . . . . . . . . . 5 4.6. GAWK Text Processing . . . . . . . . . . . . . . . . . 6 4.7. E-Mail Output . . . . . . . . . . . . . . . . . . . . . 6 4.8. File Operations . . . . . . . . . . . . . . . . . . . . 7 5. Control INI File Structure . . . . . . . . . . . . . . . . . 7 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 7 5.2. Fixed Initial Stage . . . . . . . . . . . . . . . . . . 7 5.3. Stages Specification . . . . . . . . . . . . . . . . . 7 5.4. Flow Control . . . . . . . . . . . . . . . . . . . . . 8 5.5. Error Handling . . . . . . . . . . . . . . . . . . . . 9 Copyright 1996, ITS Information Technology Solutions GmbH. 17 July 1996 IT Solutions Control DLL Page 2 5.6. Variable Locations . . . . . . . . . . . . . . . . . . 9 5.7. Boolean Values . . . . . . . . . . . . . . . . . . . . 9 5.8. File Specifications . . . . . . . . . . . . . . . . . . 10 6. Output E-Mail File Structure . . . . . . . . . . . . . . . . 10 7. Control INI File Stage Types . . . . . . . . . . . . . . . . 11 7.1. Fixed Stage Type . . . . . . . . . . . . . . . . . . . 11 7.1.1. Fixed Initial Stage . . . . . . . . . . . . . 11 7.2. Immediate Stage Types . . . . . . . . . . . . . . . . . 12 7.2.1. Flow Control Stage Types . . . . . . . . . . 12 7.2.2. Variable Assignment Stage Types . . . . . . . 14 7.2.3. User Message Stage Type . . . . . . . . . . . 15 7.2.4. Error Handling Stage Types . . . . . . . . . 15 7.3. Composed Stage Types . . . . . . . . . . . . . . . . . 16 7.3.1. File Operation Stage Types . . . . . . . . . 16 7.3.2. Text Processing Stage Type . . . . . . . . . 19 7.3.3. Output E-Mail Stage Types . . . . . . . . . . 20 8. Installation . . . . . . . . . . . . . . . . . . . . . . . . 24 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 24 8.2. Unzipping the Distribution . . . . . . . . . . . . . . 24 8.3. Copying the ITSCTRL Elements . . . . . . . . . . . . . 24 8.4. Installing the ITSCTRL Modules . . . . . . . . . . . . 24 8.5. Examining the Sources . . . . . . . . . . . . . . . . . 25 8.6. Examining the Demos . . . . . . . . . . . . . . . . . . 25 9. Software and Hardware Requirements . . . . . . . . . . . . . 25 10. Licensing . . . . . . . . . . . . . . . . . . . . . . . . . 25 11. Support . . . . . . . . . . . . . . . . . . . . . . . . . . 26 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 Appendix A - CompuServe Mail Delivery Mechanism . . . . . . . . . 27 1. Overview The IT Solutions Control DLL is a callable procedure which executes a series of stages as specified in a control INI file in order to process an input file and e-mail the result. It is invoked as a function call by and within a Windows application. The selection and sequence of stages are fully configurable by using a simple language embedded within the Windows INI format. The functionality of each stage is determined by the stage type and other parameters which are specified for the stage. The kinds of stage types available are flow control, file operations, text processing and output e-mailing. ITSCTRL is distributed as part of the IT Solutions EDI Pseudo Printer (ITSEDIPP) package. However, it can be separated from ITSEDIPP and incorporated into and used by other applications. 2. Components 2.1. ITSCTRL.DLL The ITSCTRL.DLL module is the fixed component of the product. It must reside in the Windows System directory. 17 July 1996 IT Solutions Control DLL Page 3 2.2. Control INI File The control INI file controls the actions of the module. It contains sections which hold the specification and sequence of processing stages which ITSCTRL will follow as well as variables which are available to both ITSCTRL and the stages. The name of the control file is specified by the caller, but if null or empty, defaults to ITSCTRL.INI. In ITSEDIPP, the specified name is ITSEDIPP.INI. In either case, the file must reside in the Windows directory. 2.3. Input Data File The input data file contains the raw input to the ITSCTRL processing. It is usually an ASCII text file and, in the case of ITSEDIPP, contains the ASCII rendition of the text on a printed page. Its filename is specified by the calling program and may be a temporary file, as ITSCTRL automatically makes a copy of it as its first task. 2.4. GAWKDLL Processing Module The GAWKDLL processing module is described in the document "User's Manual for the IT Solutions GNU AWK DLL". This module, which consists primarily of the files GAWK.DLL, AWKLIB.DLL and AWK scripts, is called by ITSCTRL to perform all of the non-trivial processing (pattern matching and text manipulation) of the input file to produce the intermediate files and output results. 2.5. Intermediate Data Files The intermediate files contain the work in progress of invocations of the product. There are usually several sets of these files, whose locations are determined by special assignments in the stage sections of the control INI file. All of the file operations, text processing and output mailing stage types have at least one input or output intermediate data file. 2.6. E-Mail Software In order for ITSCTRL to be able to communicate with the outside world, there must be some e-mail software available which is compatible with one of the e-mail pathways of an output e-mail stage type. Commonly-used compatible e-mail software packages are WfW Mail, MS Mail, Lotus Notes Mail, cc:Mail or WINFAX Pro. 3. ITSCTRL Invocation 3.1. Overview Because ITSCTRL is called from within a running Windows application, some preparatory programming will be necessary. The basic steps are: a) creating the input data file, b) loading the ITSCTRL.DLL module, c) getting the address of the ITSCTRL entry point function and d) calling the entry point function with the control INI filename and input data filename arguments. 17 July 1996 IT Solutions Control DLL Page 4 A "C" example of how to program all of this, JOB.C, can be found in the source code of the ITSPPD module of ITSEDIPP. When ITSEDIPP has been installed, or at least unzipped, you can navigate to the ITSPPD source directory, unzip the ITSPPD sources and find JOB.C there. 3.2. Creating the Input File Creating the input file is straightforward. You simply write the data you want processed by ITSCTRL into a file, possibly a temporary file. Note that since GAWKDLL will be working with the data, and GAWKDLL is a line-oriented text-processing program, the input file should contain plain ASCII text divided into lines. 3.3. Loading ITSCTRL and Locating the Entry Point Once the input file has been created, the calling program loads ITSCTRL.DLL. This is done using the Windows LoadLibrary() kernel function. Then the caller must get the location of the ITSCTRL entry point function, named "ExecStages", using the Windows GetProcAddress() kernel function. The entry point has the "C" calling sequence "ExecStages(char *CtrlFileName, char *InputFileName)". 3.4. Calling the Entry Point Having the two filenames and the entry point address, all that is left to do is to actually call ITSCTRL. ITSCTRL will run and return an exit value. An exit value of zero indicates success. A non-zero exit value indicates some kind of failure. In either case, the ITSCTRL.DLL module should be unloaded with the Windows FreeLibrary() kernel function after ITSCTRL returns. 4. ITSCTRL Execution 4.1. Overview The execution of ITSCTRL consists most basically of four steps: a) capture of the input file, b) update of the job sequence number, c) execution of a sequence of stages as specified in the control INI file and d) return of a return code, based on the return code of step c), to the calling program. That said, the execution of step c) can really be quite complex, depending on the content of the control INI file. The primary reason for being of ITSCTRL is to prepare for and, in step c), to execute a sequence of GAWK stages followed by an output e-mail stage. 4.2. Capture of the Input File This step always takes place first when ITSCTRL is called. The raw input file specified as an argument to the entry point is opened and read whole into a buffer. Then ITSCTRL determines where to write its copy of the file and writes it there. The location of the ITSCTRL copy of this raw file is determined by the values of two entries in the control INI file, a raw file name pattern and a job sequence number, as described below and in the section titled "Fixed Initial Stage". 17 July 1996 IT Solutions Control DLL Page 5 4.3. Update of the Job Sequence Number ITSCTRL serialises the calls to it, using the job sequence number from the control INI file as a modifier of generated file names, including the ITSCTRL raw input file name, in stages where serialised filenames are necessary. Usually, the sequence number used for a job is the one read from the control INI file. However, ITSCTRL is careful never to overwrite an existing raw input file from a previous job; if the generated raw filename names an existing file, ITSCTRL repeatedly increments the sequence number until it finds an unused raw filename. After a job sequence number has been determined which generates an unused raw input filename and the raw input contents have been written there, ITSCTRL updates the job sequence number in the control INI file to the current job sequence number plus one. Then, the next call to ITSCTRL should have an unused job sequence number right away. 4.4. Stage Execution The main task of ITSCTRL is to execute a sequence of stages as specified in the control INI file. The stages specification is really a simple program which ITSCTRL is to follow, with the goal of transforming the input file into a useful output file which is then dispatched to a destination. There are several different types of stage with which a program can be built. Among these are flow control, variable assignment, user message, error handling, file operation, text processing and output e-mail stage types. A program consists of a sequence of numbered stages, each with a stage type and arguments depending on the type. During stage execution, ITSCTRL loops in a cycle of fetching the next numbered stage, determining the stage type, calling the procedure corresponding to the stage type to carry out the stage's function, reacting to the stage's execution return value and determining the next stage number, usually the current stage number plus one. There are stage types which specify stage subroutine calls and returns, so a stage call stack is also maintained in that the stage execution machine can be called recursively. In fact, the stage execution phase begins with a subroutine call to stage number one and ends when the call returns. A typical stage program could contain stages to do the following: a) recognise the contents of the input data file, b) extract the relevant data from the input data file, c) integrate outside data into the extracted data, d) update counters or other data values based on the content of the job data, e) create a formatted output data file incorporating the integrated data, f) archive the input, intermediate and output data files in special archive directories, g) dispatch the output data file to an e-mail channel, h) provide the user with informational messages on the progress of the job and I) catch and deal with errors which may occur in the other stages. 4.5. ITSCTRL Return Code ITSCTRL returns one of two values to the calling program, depending on the outcome of the stage execution phase. If the stage 17 July 1996 IT Solutions Control DLL Page 6 execution generates an uncaught error or is aborted, then negative one is returned. If the stage execution finishes successfully, then zero is returned. 4.6. GAWK Text Processing As mentioned above, the main purpose behind ITSCTRL is to set up and execute a sequence of GAWK stages to process the input text file and then e-mail the resulting output file. This makes GAWK stage text processing the primary task of ITSCTRL -- it is where the real work takes place. When a GAWK stage type is found, ITSCTRL gathers several important elements together to prepare for a call to the GAWKDLL program and then calls it according to the GAWKDLL invocation specification, which is described in the document "User's Manual for the IT Solutions GNU AWK DLL". The elements ITSCTRL gathers include: a) input and output filenames, b) AWK script filenames, c) ITSCTRL-global and stage-local variable assignments and d) the ITSCTRL job sequence number. All of these elements are assembled into a "command line" argument list for GAWKDLL. Then, ITSCTRL loads the GAWK.DLL module, locates the entry point and calls the entry point with the argument list. Upon finishing, GAWKDLL returns an exit value which ITSCTRL evaluates and handles in its standard way -- zero for success, non-zero for failure. 4.7. E-Mail Output The second most important task of ITSCTRL is the submission of the resulting output file to an output e-mail stage. To this end, there are currently three different output e-mail stage types, MAPI, VIM and WINFAX, corresponding to three e-mail APIs on the market. Roughly, the MAPI API reaches Microsoft and compatible e-mail products, the VIM API reaches Lotus and compatible e-mail products and the WINFAX API reaches WinFax Pro. When an e-mail output stage type is found, a varying number of items are gathered, depending on the specific stage type. All of the e-mail output stage types assume that there will be an output data file, consisting of a simple header and a message data body. This data file will have been created in the correct format by an earlier stage in the job, most likely a GAWK stage. In the output data file header will be found the message destination address (or address alias) and the message subject line. The message data body is separated from the header and held in a buffer or temporary file in preparation for delivery to the API. Other items gathered by ITSCTRL include the e-mail system loginname and password and, in the case of WINFAX, things like transmission time, fax mode and resolution and extra formatting information. After the output message body and all of the items appropriate to the stage type have been gathered, ITSCTRL loads or starts the corresponding API DLL or program and calls the necessary API entry point routines to convey the data items and initiate the delivery of the output e-mail message. After this point, responsibility for delivery has been passed to the e-mail system. Upon API return, 17 July 1996 IT Solutions Control DLL Page 7 ITSCTRL unloads the API DLL and interprets and passes the e-mail system's return code back up to the stage execution loop. 4.8. File Operations Originally, file operation stage types were not part of ITSCTRL. But, it was found necessary to be able to make copies of intermediate and result data files for archival purposes. The file operation stage types provided, APPEND, COPY, DELETE, MKDIR, MOVE and RMDIR do just what one would think with files and directories in the DOS/Windows file system. 5. Control INI File Structure 5.1. Overview The control INI file has the regular Windows INI file format with [sections], assignments, consisting of entries= and =values within the sections and ;comments. The file has two special sections and multiple stage-specific sections. One special section, named "[Stages]", contains assignments specifying the sequence of stages which ITSCTRL is to carry out. The other special section, named "[Variables]", holds global variable assignments which are available to all stages and to ITSCTRL itself. Each of the stage-specific sections, having a name of the form "[ Stage]", contains an assignment giving the stage type and other assignments specific to the stage type or otherwise needed by the stage during its execution. Additional sections not used by ITSCTRL may also be in the file. 5.2. Fixed Initial Stage The "[Variables]" section of the control INI file must contain two special assignments composing the fixed initial stage, which is always executed first upon entry to ITSCTRL, before any of the programmed stages are executed. The first assignment gives the location to which ITSCTRL copies the raw input data file. It must have the form "RawFilePattern=", where the value gives a pathname. The drive and directory parts of the pathname must yield an existing directory. The filename part of the pathname must containing the string "9999", into which the four-digit job sequence number will be substituted, which must then yield a valid filename. The second assignment gives the current job sequence number and must have the form "SEQNO=". The sequence number found here will be padded with leading zeros to four digits and then substituted into the raw file pattern to yield the job's raw filename. The "SEQNO=" value will be updated (incremented) automatically by ITSCTRL. 5.3. Stages Specification The "[Stages]" section of the control INI file specifies what program stages are to be executed. Each stage has a stage number which gives the order in which the stages are to be carried out. A 17 July 1996 IT Solutions Control DLL Page 8 stage assignment has the form "Stage=". The first stage to be executed has the stage number one and thus has the entry "Stage1=". The stages are executed sequentially by stage number, with no gaps in the numbering sequence except when the next stage number has been changed explicitly via a JUMP or CALL stage (or an ONERROR stage when an error occurs). A missing stage number ends sequential execution at that point and is thus equivalent to a RETURN stage. The stage specification value string gives either the full specification of the stage, in the case of immediate stage types, or the name of the stage specification section, in the case of composed stage types. For immediate stage types, the value string takes the form of "= ". For composed stage types, the value string takes the form of "=", where the stage name gives the name of a section which fully specifies the stage. This full specification section heading has the form "[ Stage]" and the section must contain at least a stage type assignment of the form "StageType=". Note that ITSCTRL scans the stage specification value string token by token (delimited by spaces or tabs), so the first token of a composed stage name must not be an immediate stage type (case insensitive). The list of possible stage types are found below. 5.4. Flow Control As stated before, the stages are executed sequentially by stage number, so the most common flow control action is incrementing the current stage number by one to get the next stage number. However, there are provisions to alter this fixed execution of stages numbered 1 to N by using jumps and subroutine calls, both either unconditionally or conditionally, based on the value of assignments in the "[Variables]" section. This allows groups of stages to be arranged into subroutines or conditionally executed blocks. Subroutines calls can be nested or called recursively. In order to facilitate subroutine calls, an effective call stack is maintained while ITSCTRL is running. In fact, the first call on the stack is the automatic call to stage number one. Returning from a subroutine call is effected by either an explicit RETURN stage type or a missing stage number in the execution sequence. Two stage types end ITSCTRL execution immediately without retracing back up the call stack, the DONE and ABORT stage types. Also, an uncaught error in any executed stage (defined as the inability to carry out a stage successfully or a stage returning a non-zero value) will halt ITSCTRL execution immediately. For details on all of the flow control stage types, see the section on them below, titled "Flow Control Stage Types". 17 July 1996 IT Solutions Control DLL Page 9 5.5. Error Handling Normally, when ITSCTRL encounters an error in executing a stage or a stage returns a non-zero value, execution of the stage program is halted and ITSCTRL returns negative one to the calling program. However, there was a need to be able to catch errors and perform at least a partial recovery. The ONERROR stage type enables this. When a stage is specified with the ONERROR stage type, the given stage number is taken to be the stage to jump to whenever an error in stage execution occurs. This error stage number remains valid for all subsequently executed stages until either changed or revoked (by specifying no stage number or stage number zero). Furthermore, when an error is caught, the error stage number is jumped to and then the error stage number is revoked (reset to no error stage number). 5.6. Variable Locations There are many instances where a stage type requires the value of a named variable to be looked up. For example, a conditional jump stage gives the name of a variable whose value is to be tested to determine whether or not to jump, or an output e-mail stage needs the value of the e-mail system loginname variable. In the case of immediate stage types, the required named variables are looked for in the "[Variables]" section of the control INI file. Such a variable assignment would have the form "=". In the case of composed stage types, some named variables must be assigned in the specific stage section, but others can optionally be in the "[Variables]" section instead. If the named variable can be in either location, it is sought first in the local stage-specific section and, if not found, then in the global "[Variables]" section. Thus, named variables which should have the same value in multiple stages can be assigned global values in the "[Variables]" section while variables confined to one stage, or whose local value should differ from the global value of the variable, can be assigned in the specific stage section. 5.7. Boolean Values Several of the flow control stage types which perform conditional jumps or subroutine calls require a boolean value from a named variable. The way a value string is interpreted as a boolean value is as follows: a) the first non-period ('.'), non-blank, non-tab character is found, b) if the character is in the set "tTyYjJoOsSwWvV", then the boolean value is true, c) if the character is in the set "fFnN", then the boolean value is false, d) the value string is scanned as an integer number, e) if the number is non-zero, then the boolean value is true and f) the number is zero, so the boolean value is false. This allows words such as "true", "yes", "ja", "oui", "si", "wahr" and "vrai" all to be interpreted as true while "false", "no", "nein", "non", "falsch" and "faux" will be interpreted as false. The interpretation of numbers as boolean values along with the use of variable assignment, variable decrement and conditional jump 17 July 1996 IT Solutions Control DLL Page 10 stage types allows stage loops to be set up which will iterate a specific number of times. 5.8. File Specifications The fixed initial stage and all of the composed stage types act on files, often one input file and one output file. The names, or locations, of these files can usually be specified in one of two ways, either with a fixed filename or by a pattern into which the job sequence number is substituted, yielding a filename. The specification of a fixed filename has the form "FileName=", where the prefix is a stage type-specific short string telling what kind of file it is, for example "In" or "Out", and the file name string is a valid filename whose directory must exist. The specification of a filename by pattern looks like "FilePattern=", where the prefix is as above and file pattern string looks like a filename, but contains either the string "9999" or "9998". ITSCTRL will substitute the first occurrence of the string "9999" (or "9998") with the job sequence number (or the job sequence number minus one), padded with zeroes to four digits, yielding the effective filename, whose directory must exist. This scheme allows each job to generate an unique set of data files without overwriting those of a previous job. The substitution of "9998" also allows data files from the previous job to be accessed, if necessary. Note that for any one prefix there should only be one of the fixed filename or file pattern assignments in a stage section; if both are present in the same section, then ITSCTRL will find the fixed filename first and ignore the file pattern. Theoretically, as variable assignments, filename specifications could be found either locally in the specific stage section or globally in the "[Variables]" section. However, because almost all of the prefixes are shared among multiple stage types and the same stage type could appear multiple times, most of the filename specifications are limited to the specific stage section where they are needed. 6. Output E-Mail File Structure Given that the point of ITSCTRL is to transform text into a message to be mailed and then mail it, it is assumed that at some point an output e-mail file will be created, probably by a GAWK stage, and shortly thereafter an output e-mail stage will be executed. All of the output e-mail stage types expect as input a message file with a certain simple structure: a two line header followed by the message text to be mailed. The output e-mail file must have as its first line the specification of the recipient of the message. This consists of the optional string "TO:" (case insensitive) as the first space or tab delimited token on the line followed by the required recipient lookup (or short) name as a single token. All remaining tokens on the recipient line are taken to be the recipient address. The lookup name is always passed to the e-mail interface and is usually 17 July 1996 IT Solutions Control DLL Page 11 used as an abbreviation or code to look up the recipient's real address. If present, the recipient address is also passed to the e-mail interface, but how it is handled is dependent on the e-mail system. [ Experience has shown that sometimes a valid recipient address is not handled correctly by the e-mail driver. In this case it is best to put only the lookup name in the file and be sure it is in the e-mail system's address book. ] The second line of the output e-mail file gives the subject of the message. This consists of the optional string "SUBJECT:", or any part thereof down to "SU:", (case insensitive) as the first space or tab delimited token on the line followed by the remaining tokens, which are all taken to be the message subject. If there are no subject tokens, then the string "EDI Message" is used as the subject. The message subject is passed to the e-mail interface and will eventually be available to the recipient. Therefore, it is recommended that a subject is given which will help the recipient categorise and process the message, perhaps containing a value reflecting a message serial number for messages between the sender and recipient. The remaining lines of the output e-mail file, that is, the third line through the end, are the body of the e-mail message. They are passed unchanged to the e-mail interface. 7. Control INI File Stage Types In the stage type specifications below, many stage entries resolve to filenames, which can be specified either by a fixed filename or by a filename pattern (with the job sequence number). Those entries where either choice is possible are marked by asterisks ('*') in the syntax specification. An explanation of filename resolution is given above. Some stage types have entries which must appear locally in the specific stage section and not in the global "[Variables]" section; these are marked with a percent sign ('%') in the syntax specification. Some stage type specifications have entries which are optional; these are marked by plus signs ('+') in the syntax specification. 7.1. Fixed Stage Type The assignments composing this stage type specification will be found in the "[Variables]" section of the control INI file. 7.1.1. Fixed Initial Stage Syntax: SEQNO= * RawFilePattern= + DEBUG= Example: SEQNO=0123 RawFilePattern=C:\ITSEDIPP\RAW\RAW.9999.TXT The fixed initial stage is always executed first by ITSCTRL. It makes a copy of the input data file, which may have been a temporary file, and establishes the job sequence number. The location of the input data file copy is determined by the value of the "RawFileName=" assignment alone or the values of the 17 July 1996 IT Solutions Control DLL Page 12 "RawFilePattern=" and "SEQNO=" assignments together. If a "RawFileName=" is found, the input data file is copied unconditionally to that filename and the value in "SEQNO=" is taken as the job sequence number. Otherwise, a "RawFilePattern=" must be present, containing a valid pattern (with the string "9999"). The "SEQNO=" value will be substituted into the pattern, yielding the raw file name. ITSCTRL tests whether this file already exists, and if not, copies the input data file to the generated raw file name. However, if the file does already exist, then "SEQNO=" is incremented and subsequent file names tested until one is found which does not exist or 9999 is reached. In any case, "SEQNO=" is left with a value of the newly determined job sequence number plus one, so that it is ready for the next call to ITSCTRL. 7.2. Immediate Stage Types The assignments composing these stage types specifications will be found in the "[Stages]" section of the control INI file. 7.2.1. Flow Control Stage Types 7.2.1.1. Missing Stage Syntax: Example: Syntax: ;Stage= Example: ;Stage5=Stage is commented out, and therefore missing During execution, the number of the next stage is usually the number of the current stage plus one, except in the case of a jump, call or error. If the stage corresponding to the next stage number is missing (or commented out), then it is interpreted as being a RETURN stage. This causes the execution flow to jump back to the return address stage number on the stack or, if no CALL stage was executed and active, ITSCTRL execution will cease and return to the calling program as if a DONE stage were encountered. 7.2.1.2. CALL Syntax: Stage=CALL Example: Stage5=CALL 100 The CALL stage executes a subroutine call to the given stage number. When execution of the subroutine call is finished, either via a RETURN stage or a missing stage, then execution is resumed with the stage after the CALL stage. If the CALL stage refers to a missing stage number, then the missing stage is held to be a RETURN stage and the CALL stage will have done nothing. Multiple CALL stages can be nested. 7.2.1.3. CONDCALL Syntax: Stage=CONDCALL Example: Stage5=CONDCALL IsPurchaseOrder 100 The CONDCALL stage is similar to the CALL stage except that the execution of the subroutine is dependent on the boolean value of the 17 July 1996 IT Solutions Control DLL Page 13 named variable, which should be found in the "[Variables]" section. See above for how boolean values of named variables are interpreted. If the named variable does not exist then its boolean value is false. If the boolean value of the named variable is true, then a subroutine call is made to the given stage number, as in a CALL stage. Otherwise, no subroutine call is made and execution continues with the next stage number. 7.2.1.4. CONDJUMP Syntax: Stage=CONDJUMP Example: Stage5=CONDJUMP IterationCounter 100 The CONDJUMP stage type is similar to the JUMP stage type except that the execution of the jump is dependent on the boolean value of the named variable, which should be found in the "[Variables]" section. See above for how boolean values of named variables are interpreted. If the named variable does not exist then its boolean value is false. If the boolean value of the named variable is true, then the execution flow is diverted to the given stage number, as in a JUMP stage. Otherwise, no jump is made and execution continues with the next stage number. 7.2.1.5. DONE Syntax: Stage=DONE Example: Stage5=DONE The DONE stage type, when reached, tells ITSCTRL that all processing has been finished successfully and ITSCTRL can return to the caller with a successful return code of zero. Regardless of how deeply nested the call stack may be, the DONE stage type causes ITSCTRL to end immediately, without tracing back up the call stack. 7.2.1.6. IF Syntax: Stage=IF Example: IF IsPurchaseOrder 100 The IF stage type operates exactly the same as the CONDJUMP and IFJUMP stage types do. 7.2.1.7. IFCALL Syntax: Stage=IFCALL Example: Stage5=IFCALL IterationCounter 100 The IFCALL stage type operates exactly the same as the CONDCALL stage type does. 7.2.1.8. IFJUMP Syntax: Stage=IFJUMP Example: Stage5=IFJUMP IsPurchaseOrder 100 The IFJUMP stage type operates exactly the same as the CONDJUMP and IF stage types do. 17 July 1996 IT Solutions Control DLL Page 14 7.2.1.9. JUMP Syntax: Stage=JUMP Example: Stage5=JUMP 100 The JUMP stage causes the execution flow to jump to the given stage number. It does not affect the state of the call stack. 7.2.1.10. NULL Syntax: Stage=NULL Example: Stage5=NULL The NULL stage type does nothing; execution continues with the next stage number. The NULL stage type is a convenient place holder, often used as a substitute stage type when a stage in a sequence needs to be omitted without causing all the subsequent stages to need renumbering. 7.2.1.11. RETURN Syntax: Stage=RETURN Example: Stage5=RETURN The RETURN stage type causes the execution flow to go back up one level on the call stack and resume with the stage number after the last-executed CALL (or carried-out CONDCALL) stage type. If no subroutine call has been executed, or all previous subroutine calls have already been returned, then the RETURN stage type causes ITSCTRL to halt the execution flow and return to the calling program, as if a DONE stage type had been encountered. 7.2.2. Variable Assignment Stage Types 7.2.2.1. ASSIGN Syntax: Stage=ASSIGN Example: Stage5=ASSIGN ErrorDescription File Not Found Example: Stage5=ASSIGN IsPurchaseOrder FALSE Example: Stage5=ASSIGN IterationCounter 5 Example: Stage5=ASSIGN NullString The ASSIGN stage type causes the named variable in the "[Variables]" section of the control INI file to receive the given value string. The variable name must be a single word. If the named variable does not exist, it is created. The assigned value string may contain any set of tokens, numeric, boolean or string, and may even be empty. 7.2.2.2. DECREMENT Syntax: Stage=DECREMENT Example: Stage5=DECREMENT IterationCounter The DECREMENT stage type subtracts one from the numeric value of the named variable in the "[Variables]" section of the control INI file and reassigns the new value to the variable. The old 17 July 1996 IT Solutions Control DLL Page 15 numeric value is determined in the manner of the Windows function GetProfileInt() having a default of zero. If the variable's value is a non-numeric string or the variable is not found, then the old value is zero and the new value will be minus one. This stage type can be used with the ASSIGN and CONDJUMP stage types to make loops which execute a specific number of times. 7.2.3. User Message Stage Type 7.2.3.1. MESSAGE Syntax: Stage=MESSAGE Example: Stage5=MESSAGE Purchase Order Recognized The MESSAGE stage type is used to deliver a fixed informational message to the user at runtime via a Windows message box. A message box containing the given message string, which may be empty or consist of multiple words, and having only an "OK" button is created in a window on the screen. The user must select the "OK" button before ITSCTRL processing can proceed. It is important that the user does NOT do something which would initiate another ITSCTRL job while the MESSAGE stage message box is being shown. 7.2.4. Error Handling Stage Types 7.2.4.1. ABORT Syntax: Stage=ABORT Example: Stage5=ABORT Syntax: Stage=ABORT Example: Stage5=ABORT -99 The ABORT stage type, when reached, tells ITSCTRL that the processing of the job has been finished unsuccessfully. A message box containing a short message plus the exit code, if any, is displayed in a window on the screen. The user must choose the "OK" button of the message box at which point ITSCTRL returns to the calling program with an unsuccessful return code of minus one. Regardless of how deeply nested the call stack may be, the ABORT stage type causes ITSCTRL to end immediately, without tracing back up the call stack. It is important that the user does NOT do something which would initiate another ITSCTRL job while the ABORT stage message box is being shown. 7.2.4.2. ONERROR Syntax: Stage=ONERROR Example: Stage5=ONERROR Syntax: Stage=ONERROR Example: Stage5=ONERROR 0 Example: Stage5=ONERROR 900 At every subroutine call level, including the automatic initial call to stage number one, ITSCTRL keeps an error destination stage number, to which a jump, within the subroutine call, is made when an error in executing a stage is encountered or a stage returns a 17 July 1996 IT Solutions Control DLL Page 16 non-zero return status. This error destination stage number for a level is set or cleared with the ONERROR stage type. When the ONERROR stage type with a stage number is encountered, the destination stage number within the active subroutine call is set. If an error occurs in any of the subsequent stages of the subroutine, the error is caught, the destination error stage is jumped to and the saved destination error stage number is cleared to zero. When the ONERROR stage type with no stage number is encountered, the destination error stage number within the active subroutine call is reset to zero. If an error occurs in a stage and the destination error stage number at that subroutine call level has not been set or has been set, reset or cleared to zero, then the error is not caught and causes the subroutine to return immediately one level up in the call stack with an error return status, which the calling subroutine may possibly catch. If the calling subroutine does not catch the error then it, in turn, returns an error return status to its calling subroutine. If an uncaught error occurs in, or is propagated up the call stack to, the automatic initial call subsequent to stage number one, then an error return code of minus one is returned to the calling program as ITSCTRL quits. 7.3. Composed Stage Types The assignments composing these stage types specifications will be found in their own sections of the control INI file, as named in an assignment in the "[Stages]" section. 7.3.1. File Operation Stage Types 7.3.1.1. APPEND Syntax: [ Stage] % StageType=APPEND *% InFilePattern= *% OutFileName= Example: [Append Data To Log Stage] StageType=APPEND InFilePattern=C:\ITSEDIPP\JOBS\JOB9999\DATA.TXT OutFileName=F:\LOG\DATAOUT.TXT The APPEND stage type causes the contents of the input file to be appended to the end of the output file. The input file name is determined, as described in the section titled "File Specification" above, from the assignment having the "In" prefix. The output filename is determined from the assignment with the prefix "Out". Both filename specifications must be in the local stage-specific section. If the output file does not already exist, it will be created. 17 July 1996 IT Solutions Control DLL Page 17 7.3.1.2. COPY Syntax: [ Stage] % StageType=COPY *% InFilePattern= *% OutFileName= Example: [Copy EDI To Last Log Stage] StageType=COPY InFilePattern=C:\ITSEDIPP\JOBS\JOB9999\EDI.TXT OutFileName=F:\LOG\LASTOUT.TXT The COPY stage type causes the input file to be copied to the output file. The input file name is determined, as described in the section titled "File Specification" above, from the assignment having the "In" prefix. The output filename is determined from the assignment with the prefix "Out". Both filename specifications must be in the local stage-specific section. If the output file already exists, it will be overwritten. 7.3.1.3. DELETE Syntax: [ Stage] % StageType=DELETE *% DeleteFilePattern= Example: [Delete Temp File Stage] StageType=DELETE DeleteFilePattern=D:\TEMP\TEMP9999.TXT The DELETE stage type deletes a file. The filename is determined, as described in the section titled "File Specification" above, from the assignment having the "Delete" prefix. The filename specification must be in the local stage-specific section. 7.3.1.4. MKDIR Syntax: [ Stage] % StageType=MKDIR *% MkdirFilePattern= Example: [Make Temp Directory Stage] StageType=MKDIR MkdirFilePattern=D:\ITSEDIPP\JOBS\JOB9999 The MKDIR stage type is used to create a file system directory. The filename determination mechanism is used to obtain the name of the directory to be created; the directory name specification assignment has the prefix "Mkdir". Do not be confused by the component "File" in the directory name assignment entry, a directory is what will be created. The "File" part is there only to enable the use of the same name generation mechanism as for files. The directory name specification must be in the local stage-specific section. 17 July 1996 IT Solutions Control DLL Page 18 7.3.1.5. MOVE Syntax: [ Stage] % StageType=MOVE *% InFilePattern= *% OutFileName= Example: [Move EDI To Failed Stage] StageType=MOVE InFilePattern=C:\ITSEDIPP\EDI\EDI9999.TXT OutFileName=F:\FAILED\LASTEDI.TXT The MOVE stage type causes the input file to be moved to the output file. The input file name is determined, as described in the section titled "File Specification" above, from the assignment having the "In" prefix. The output filename is determined from the assignment with the prefix "Out". Both filename specifications must be in the local stage-specific section. If the output file already exists, it will be overwritten. After a successful move, the input file will no longer be found in the old location. 7.3.1.6. RMDIR Syntax: [ Stage] % StageType=RMDIR *% RmdirFilePattern= Example: [Remove Temp Directory Stage] StageType=RMDIR RmdirFilePattern=D:\TEMP9999 The RMDIR stage type is used to remove a file system directory. The filename determination mechanism is used to obtain the name of the directory to be removed; the directory name specification assignment has the prefix "Rmdir". Do not be confused by the component "File" in the directory name assignment entry, a directory is what will be removed. The "File" part is there only to enable the use of the same name generation mechanism as for files. The directory name specification must be in the local stage-specific section. The directory to be removed must be empty. 17 July 1996 IT Solutions Control DLL Page 19 7.3.2. Text Processing Stage Type 7.3.2.1. GAWK Syntax: [ Stage] % StageType=GAWK % ScriptFileName= +*% InFilePattern= +*% OutFilePattern= + = + GAWKUseCallerStack= + GAWKUseLocalStack= Example: [Convert Flat to EDI Stage] StageType=GAWK ScriptFileName=C:\AWK\POEDI.AWK,C:\AWK\LIB.AWK InFilePattern=C:\ITSEDIPP\FLAT\FLAT9999.TXT OutFilePattern=C:\ITSEDIPP\EDI\EDI9999.TXT FOO=123456 BAR=ABCDEF Given that GAWKDLL is the workhorse of the product, the GAWK stage type usually appears multiple times in every ITSCTRL application. The point of ITSCTRL is, after all, to capture the input data, process it with multiple GAWKDLL passes and e-mail it somewhere. Each GAWK stage must have an AWK script file specification, in the form of an assignment with entry "ScriptFileName=" ("Pattern" is not allowed in this case). The specification may actually consist of a list of comma-separated AWK script files, but there must be at least one AWK script file in the list. The AWK script file specification must be in the local stage-specific section. When multiple AWK script files are given, it is common that the first is a stage-specific AWK script and the rest are AWK scripts containing libraries of AWK function definitions. Taken together, the specified AWK script files govern what GAWK processing is to take place in the GAWK stage. For a description of what a GAWK stage's AWK script files must and may contain, see the document "User's Manual for the IT Solutions GNU AWK DLL" and the other documents referred to therein. A GAWK stage type usually, but not always, has both input and output filename specifications assignment with the prefixes "In" and "Out". The filename determination mechanism is used to finalise the names of the input and output files. If present, both specifications must be in the local stage-specific section. Whether present or not, the final input and output filenames are treated specially by ITSCTRL. Two assignments of the form "INFILE=" and "OUTFILE=" are added at runtime to the local stage-specific section in the control INI file so that variables with the names "INFILE" and "OUTFILE" will be available to GAWKDLL at runtime, using the mechanism explained below. ITSCTRL also handles the job sequence number specially within a GAWK stage. An assignment of the form "GAWKSEQNO=" 17 July 1996 IT Solutions Control DLL Page 20 is also added at runtime to the local stage-specific section so GAWKDLL will be able to use the job sequence number at runtime, again using the variable mechanism explained below. Also in the local GAWK stage-specific section can appear any number of other variable assignments which the user wishes to make available to GAWKDLL at runtime. Variable assignments which more than one GAWK stage will need can appear globally in the "[Variables]" section of the control INI file, although local assignments having the same variable names will take precedence over these. Once ITSCTRL has written the three automatically generated assignments, the "command line" for the stage's GAWKDLL call is assembled. This consists first of the name of the module, "GAWKDLL", next all of the variable assignments found in the global "[Variables]" section of the control INI file, then all of the variable assignments found in the local stage-specific section (including the automatic assignments) and finally the specification of the script filenames. When the "command line" has been completed, ITSEDIPP loads GAWK.DLL and runs its only function, "GAWKmain", with the "command line" as its input parameters. GAWKmain returns a status code which is interpreted by ITSCTRL, with zero meaning success and any non-zero value meaning some kind of failure or error. The last issue concerning the GAWK stage type is a technical one, in particular, which GAWKDLL entry point should be used in order to get the desired runtime stack configuration within GAWKDLL. The two optional, mutually-exclusive boolean assignments, "GAWKUseCallerStack=" and "GAWKUseLocalStack=", can be used to specify explicitly which stack configuration will be used. How to recognise whether a change is necessary and decide which to use is described in detail in the GAWKDLL User's Guide. Normally, the default configuration, using neither of the assignments, is adequate. However, if (only under Windows 3.1x) one or the other assignments is true, then the corresponding stack configuration will be forced via choice of GAWKDLL entry point. 7.3.3. Output E-Mail Stage Types All of the output e-mail stage types need at least an input file having the format described above in the section titled "Output E-Mail File Structure". 17 July 1996 IT Solutions Control DLL Page 21 7.3.3.1. MAPI Syntax: [ Stage] % StageType=MAPI + Login= + Password= *% InFilePattern= Example: [Mail EDI To MAPI Stage] StageType=MAPI Login=editest Password=tsetide InFilePattern=C:\ITSEDIPP\EDI\EDI9999.TXT The MAPI stage type is used to submit an e-mail message to a MAPI compatible e-mail system. The only required assignment is the name of an input file which must be in the e-mail message format described earlier. The filename is determined, as described in the section titled "File Specification" above, from the assignment having the "In" prefix. The filename specification must be in the local stage-specific section. For the establishment of the link to the e-mail system via MAPI, the "Login=" and "Password=" assignments may appear locally in the stage-specific section or globally in the "[Variables]" section of the control INI file. If either or both of the assignments exist, they will be read and the values passed to MAPI during establishment of the MAPI session. Otherwise, MAPI will look for them in the MSMAIL.INI file. If either is still not found, MAPI will obtain them from the user at runtime via a MAPI login dialog. [ Experience has shown that even if they are found in the control INI file, are valid and are passed to the MAPI logon call, the MAPI login dialog will appear. To avoid the dialog, put them in MSMAIL.INI and not in the control INI file. ] 7.3.3.2. VIM Syntax: [ Stage] % StageType=VIM + Login= + Password= *% InFilePattern= Example: [Mail EDI to VIM Stage] StageType=VIM Login=editest Password=tsetide InFilePattern=C:\ITSEDIPP\EDI\EDI9999.TXT The VIM stage type is used to submit an e-mail message to a VIM compatible e-mail system. The only required assignment is the name of an input file which must be in the e-mail message format described earlier. The filename is determined, as described in the section titled "File Specification" above, from the assignment having the "In" prefix. The filename specification must be in the local stage-specific section. For the establishment of the link to the e-mail system via VIM, the "Login=" and "Password=" assignments may appear locally in the 17 July 1996 IT Solutions Control DLL Page 22 stage-specific section or globally in the "[Variables]" section of the control INI file. If either or both of the assignments exist, they will be read and the values passed to VIM during establishment of the VIM session. 7.3.3.3. WINFAX Syntax: [ Stage] % StageType=WINFAX WINFAXFileName= *% InFilePattern= *% TempFilePattern= + SendDateTime= + BillingCode= + FaxMode= + FaxResolution= + FaxCoverFileName= + CoverFillText= + MessageAsAttachment= + DEBUG= Example: [Fax ASCII to WINFAX Stage] StageType=WINFAX WINFAXFileName=C:\WINFAX\WINFAX.EXE InFilePattern=C:\ITSEDIPP\ASCII\ASCI9999.TXT TempFilePattern=D:\TEMP\WNFX9999.TXT The WINFAX stage type is used to submit an e-mail message to the WinFax Pro DDE interface. While it would not make much sense to fax an EDI-format message, this stage type is ideal for sending messages which have been reconverted back into an human-readable form. Only three assignments are required: the name of an input file, which must be in the e-mail message format described earlier, the name of a temporary file, to which the e-mail message content only is copied for submission to WinFax, and the name of the WinFax program filename. The input and temporary filenames are determined, as described in the section titled "File Specification" above, from the assignments having the "In" and "Temp" prefixes, respectively. The filename specifications must be in the local stage-specific section. The WinFax program name assignment must have the entry "WINFAXFileName=" (not "Pattern"), but may appear either locally or globally. There are many different options for the WINFAX stage type, all of which are described in detail in the Delrina WinFax PRO 4.0 User's Guide. Following is a quick overview of the options shown above. The local or global "DEBUG=" assignment, if set to a true value, causes intermediate debugging information to be displayed in message box windows as the other options are being processed. The local or global "SendDateTime=" assignment takes a value string which specifies when WinFax should actually send the faxed job. It can contain either an absolute specification or one relative to the current date and time. If the first non-blank, 17 July 1996 IT Solutions Control DLL Page 23 non-tab character of the value is a plus sign ('+'), then the value is scanned as a relative date and time, otherwise it is scanned as an absolute date and time. A relative time is scanned backwards from the end to the beginning. It consists of up to two digits of seconds, preceded by an optional delimiter, preceded by up to two digits of minutes, preceded by an optional delimiter, preceded by up to two digits of hours, preceded by an optional delimiter, preceded by up to two digits of days, preceded by an optional delimiter, preceded by up to two digits of months, preceded by an optional delimiter, preceded by up to two digits of years, preceded by anything back to the plus sign. In each case, the optional delimiter consists of one character from the set "/-:;.,". Relative times are perhaps best explained by example. The string "+9" means now plus nine seconds. The strings "+900" and "+9:" both mean now plus nine minutes. The string "+9:9:9" means now plus nine hours, nine minutes and nine seconds. The strings "+1-00;00/00" and "+1,,," both mean now plus exactly one day. An absolute time is also scanned backwards from the end to the beginning. It consists of up to two digits of seconds, preceded by an optional delimiter, preceded by up to two digits of minutes, preceded by an optional delimiter, preceded by up to two digits of hours, preceded by an optional delimiter, preceded by up to two digits of days, preceded by an optional delimiter, preceded by up to two digits of months, preceded by an optional delimiter, preceded by up to four digits of years. In each case, the optional delimiter consists of one character from the set "/-:;.,". All unspecified parts of an absolute date and time are given sensible values based on the current date and time, and all specified parts are validated and adjusted where invalid. All year specifications are adjusted to fall between 1990 and 2089, that is, 0 to 89 have 2000 added, 90 to 99 have 1900 added, 100 to 1989 are set to 1990 and 2090 and above are set to 2089. Finally, specifications where nothing or only the seconds were specified are rounded up to now plus one minute; specifications where only the minutes and seconds were specified are understood to be modulo one hour, so the job will go at the given minute and second within the 60 minutes; specifications where only hours, minutes and seconds are specified are understood to be modulo one day, so the job will go at the given hour, minute and second within the next 24 hours. If a local or global "BillingCode=" assignment is present, the first 26 characters of the value are simply passed to WinFax as the fax job's billing code value. If a global or local "FaxMode=" assignment is found, then the value is passed to WinFax as the job's transmission type. Valid mode values are "Fax", "BFT" (binary file transfer) and "Compressed BFT" (WinFax to WinFax only); the default is "Fax". If a local or global "FaxResolution=" assignment is given, then the value is passed to WinFax as the resolution setting with which the fax should be sent. Valid resolution values are "HIGH" and "LOW"; the default is "LOW". 17 July 1996 IT Solutions Control DLL Page 24 If there is a global or local "FaxCoverFileName=" (not "Pattern") assignment, then the fax job is submitted to WinFax as having a fax cover page, which must be in the WinFax cover page format. If there is a global or local "CoverFillText=" assignment, then the first 4096 characters of the value of the assignment are used to fill the cover page and the e-mail message file content is sent as a separate attachment to the cover page, in the named temporary file. Otherwise, the first 4096 characters of the e-mail message file content are used to fill the cover page, unless there is a local or global "MessageAsAttachment=" assignment whose value is true, in which case the e-mail message file content is transmitted as a separate attachment to an unfilled cover page, in the named temporary file. 8. Installation 8.1. Overview Although ITSCTRL is distributed as part of ITSEDIPP, it can be used independently. To install ITSCTRL without ITSEDIPP requires that the distribution file on the ITSEDIPP installation diskette be unzipped, the ITSCTRL and GAWKDLL elements copied from the ITSEDIPP directory and the ITSCTRL.DLL, GAWK.DLL and AWKLIB.DLL object modules copied to the Windows System directory. At this point, the ITSEDIPP directory can be discarded, however, it is recommended that it be retained for a while, at least at first, for the examples in the demo directories and the "C" code example in the ITSPPD component of how to set up and call ITSCTRL. 8.2. Unzipping the Distribution ITSP20A.EXE is the self-extracting .ZIP distribution file for ITSEDIPP. To get only ITSCTRL, you should install the ITSEDIPP directory by hand. Copy the file ITSP20A.EXE to the directory where you wish the ITSEDIPP directory to be installed. Then call it with the command "ITSP20A -e -d" and it will unzip itself. 8.3. Copying the ITSCTRL Elements ITSCTRL's object file, ITSCTRL.DLL, and GAWKDLL's two object files, GAWK.DLL and AWKLIB.DLL, are unpacked to the ITSEDIPP\BIN directory by ITSP20A.EXE. Create a new directory for ITSCTRL files and copy the three object files there. ITSCTRL's and GAWKDLL's sources will be found in the directories ITSEDIPP\SRC\ITSCTRL, ITSEDIPP\SRC\AWKLIB and ITSEDIPP\SRC\GAWKDLL. Copy these three directories to your new ITSCTRL directory. The documentation for ITSCTRL and GAWKDLL are the files ITSCTRL.* and GAWKDLL.* in the directory ITSEDIPP\DOC. Copy them too to the new directory. At this point, you have all of the parts of ITSCTRL and GAWKDLL in your new directory, so you can delete the ITSEDIPP directory if you wish. 8.4. Installing the ITSCTRL Modules Once you have the ITSCTRL files segregated from ITSEDIPP, you can install them by copying ITSCTRL.DLL, GAWK.DLL and AWKLIB.DLL to the Windows System directory, commonly \WINDOWS\SYSTEM. 17 July 1996 IT Solutions Control DLL Page 25 8.5. Examining the Sources The source code is included in order to fulfil the provision of the GNU General Public License that you have free access to the source code to change as you wish. The source files are packed in .ZIP files, for which you will need an unzip program, for example PKUNZIP, to unpack. If you believe you can make anything of the sources, then you will know where to get an unzip program on your own and probably already have one. 8.6. Examining the Demos The ITSEDIPP distribution contains six demos ranging from a very simple first demo to an overly complex fifth demo and an useable sixth demo. These demos can be found in the subdirectories of the ITSEDIPP\DEMO directory of the full ITSEDIPP distribution. The vast majority of each ITSEDIPP demo consists of code for driving ITSCTRL and GAWKDLL. So, with the exception of a few assignments in the "[Variables]" section of each demo's ITSEDIPP.INI file, each ITSEDIPP demo is really an ITSCTRL demo. 9. Software and Hardware Requirements The software requirements are Windows 3.xx or Windows 95 (ITSCTRL has not been tested under Windows NT) and a Windows application programmed or configured to call ITSCTRL, commonly the ITSPPD printer driver of the ITSEDIPP product as a whole. If any GAWK stage types are used, which is always the case, then GAWKDLL will also be required. This is not a problem, as GAWKDLL is distributed along with ITSCTRL. If any of the three output e-mail stage types is used, then the software package, usually an e-mail system, corresponding to the stage type used must be available. If the MAPI stage type is used, then there must be a MAPI-compatible e-mail system, such as WfW Mail or MS Mail, present. If the VIM stage type is used, there must be a VIM-compatible e-mail system, such as cc:Mail or Lotus Notes Mail, on the machine. If the WINFAX stage type is used, then the WinFax Pro 4.0 software must be available. There is a special case where WfW Mail is used along with the CompuServe-MS Mail driver, available from CompuServe, which is described below in Appendix A. The hardware requirement is a machine which can run the chosen software configuration. ITSCTRL itself imposes no special hardware requirements. 10. Licensing Following is the standard licensing statement for all GNU-"Free" software: ITSCTRL is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by 17 July 1996 IT Solutions Control DLL Page 26 the Free Software Foundation; either version 2 of the License, or (at your option) any later version. ITSCTRL is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with ITSCTRL; see the file COPYING. If not, write to the Free Software Foundation, Inc, 675 Mass Ave, Cambridge, MA 02139, USA. 11. Support The author of ITSCTRL, IT Solutions, will provide support at a fair price to users who need it. The contact information is: "IT Solutions" ITS Information Technology Solutions GmbH Untere Grasstr. 10 D - 81541 Munich Germany Phone: +49 (89) 69708525 E-Mail: walkerj at compuserve dot com 12. References User's Manual for the IT Solutions GNU AWK DLL (GAWKDLL), Version 2.0, James Gray Walker, ITS Information Technology Solutions GmbH, 1996. Programmer's Guide, Messaging Application Programming Interface (MAPI), Version 1.0, Microsoft Windows, Microsoft Corporation, 1993. Programmer's Reference, Messaging Application Programming Interface (MAPI), Version 1.0, Microsoft Windows, Microsoft Corporation, 1993. Windows for Workgroups Resource Kit, Chapter 12 - Mail, Microsoft Corporation, 1993. Administrator's Guide, Microsoft Mail, Electronic Mail for PC Networks, Microsoft Corporation, 1993. User's Guide, Microsoft Mail, Electronic Mail for PC Networks, Workstation Software for Windows, Microsoft Corporation, 1992. Lotus VIM Developer's Toolkit for DOS, Windows, and OS/2, Lotus Development Corporation, 1993. Lotus Notes Administrator's Guide, Lotus Development Corporation, 1993. Lotus Notes Help, Chapter 3 - Using Mail, Lotus Development Corporation, 1993. 17 July 1996 IT Solutions Control DLL Page 27 cc:Mail for Windows User's Guide, Lotus Development Corporation, 1993. Delrina WinFax PRO 4.0 User's Guide, Delrina Corporation, 1994. CompuServe-MS Mail Driver, Documentation Accompanying Product from CompuServe, CompuServe Incorporated, 1994. Appendix A - CompuServe Mail Delivery Mechanism A.1. CompuServe-Microsoft Mail Driver The CS-MS Mail driver provides a transport mechanism for MS Mail to exchange e-mail messages via CompuServe to recipients on nodes directly or indirectly connected to the CompuServe computers. It is provided free by CompuServe and works with the Workgroup MS Mail front-end delivered with WfW 3.11 or the MS Mail or MS Exchange add-ons for Windows 3.1 and up. One part of the CS-MS Mail driver provides an interface to the user's local CompuServe Address Book for address validation when e-mail messages are being submitted. A second part of the driver is a Windows program which waits in the background and wakes up MS Mail to exchange e-mail with CompuServe when certain conditions are met, such as amount of mail waiting, current time, or interval of time. A third part of the driver actually provides the e-mail exchange transport using the user's local CompuServe CIS.INI file containing dialup and connection information. Configuration details of the CS-MS Mail driver are beyond the scope of this document, and can be found in the documentation delivered with the product by CompuServe. A.2. Microsoft Mail Driver Switcher The Workgroups version of MS Mail can only support one transport mechanism at a time. So, if CS-MS Mail transport is configured, then the normal Workgroup MS Mail transport does not work. CompuServe provides a program which allows the user to manually switch between the two transport mechanisms. Configuration details of the MS Mail driver switcher are beyond the scope of this document, and can be found in the documentation delivered with the product by CompuServe. A.3. Advantages of the CompuServe-MS Mail Driver There are several important advantages to using the CompuServe- MS Mail driver. First is the initial price: it is essentially free to users with WfW 3.11 who already use CompuServe. Second is the operating price: CompuServe is a cost-effective way of sending small to moderate quantities of e-mail to connected VANs and the world network. Third is connectivity: CompuServe is well connected, 17 July 1996 IT Solutions Control DLL Page 28 with connections to the Internet, MCIMail, AT&T Mail 400, Western Union 400, Advantis, Unisource, BT Messaging Services, DBP Telebox 400, Infonet, and Sprint Mail, among others.