Microsoftware Monthly 1995 December: OS/2 Programming Power Tools

home *** CD-ROM | disk | FTP | other *** search

/ Microsoftware Monthly 19…2 Programming Power Tools / MASO9512.ISO / smart / sm_prog2.inf (.txt) < prev next >

Wrap

OS/2 Help File | 1995-05-10 | 103.2 KB | 3,544 lines

ΓòÉΓòÉΓòÉ 1. The SMART Programming Guide ΓòÉΓòÉΓòÉ The SMART Programming Guide UDMD and MiCL Version 2.1B May 1995 (C) 1991, 1994, 1995 One Up Corporation All Rights Reserved Notice Table of Contents ΓòÉΓòÉΓòÉ 2. Notice ΓòÉΓòÉΓòÉ ** NOTICE ** This document may not, in whole or in part, be copied, reproduced, photocopied, translated, or reproduced to any electronic medium or machine readable form without prior written consent from One Up Corporation. This publication could contain technical inaccuracies or typographical errors. As changes are periodically made to the information herein; these changes may be incorporated in new additions of the publication. One Up Corporation may make improvements and/or changes in the product and/or the program described in this publication at any time. One Up Corporation is not responsible for any direct or indirect damage or loss of business resulting from inaccuracies or omissions in this publication. The specifications contained in this document are subject to change without notice. SMART - Source Migration Analysis Reporting Toolset is a trademark of One Up Corporation. OS/2, Presentation Manager are trademarks of the International Business Machines Corporation. IBM is a registered trademark of the International Business Machines Corporation. Other trademarks are property of their respective companies. CONTENTS ΓòÉΓòÉΓòÉ 3. Table of Contents ΓòÉΓòÉΓòÉ Section 1 - UDMD Programming Introduction Format Tags .Notice .Table .Version .Date .Keyword .SComment .LComment .Sample .Prototyp .Template .Refer .Command .Notes Programming Notes Section 2 - MiCL Programming Introduction General Language Description Variables and Constants Strings and Quotations SMART Built-in Functions SmDisplayDlg( ) SmGetListName( ) SmGetListPath( ) SmGetSmartPath( ) SmIgnoreKeyword( ) SmListDlg( ) SmLoadVars( ) SmMigrateKeyword( ) SmNoComment( ) SmNoMigrate( ) SmOutputLine( ) SmOutputNote( ) SmPromptDlg( ) SmRemove( ) SmSaveVars( ) SmSendToEditor( ) MiCL Instructions Event Command Procedures Programming Notes and Tips MiCL Basics Preset Variables Two MiCL Examples Pre and Post Command Sets Use of Templates Use of Dialog Functions Migration Control Migration Notes and Comments Global, Static and Local Variables String and Variable Evaluation Launching the Editor Testing MiCL Command Sets Reference Reserved Words Keyword Identifier Codes Navigation Links CONTINUE - Section 1 ΓòÉΓòÉΓòÉ 4. Section 1 - UDMD Programming ΓòÉΓòÉΓòÉ User Defined Migration Database programming Introduction Format Tags Programming Notes Navigation Links CONTINUE - Introduction BACK - Table of Contents ΓòÉΓòÉΓòÉ 4.1. UDMD - Introduction ΓòÉΓòÉΓòÉ UDMD - Introduction Introduction - Programming a User Defined Migration Data Base Input for the creation of User Databases (UDMD) is an ASCII text file containing format tags and data. One database at a time can be used in conjunction with a SMART Migration Database for analysis and Migration of program source code. The User Migration Dictionary (text File) is transformed into SMART Migration database format and tables using the utility function under "Tables", "Create User UDMD" under the main menu of SMART. A sample of this input text file follows: .Notice =Copyright (c) 1993 One Up Corporation, All Rights Reserved .Table =OS/2 1.3 to OS/2 2.1 .Version =1.0 .Date =11-03-93 .Keyword =010 020 130 DosFindFirst2 .SComment=Parameters changed to ULONG and return structure changed .LComment=Parameters changed to ULONG values. Note that the variable =to receive the number of matching entries (addressed by the =6th parameter) has been changed to a ULONG value. =DosFindFirst now includes additional attribute flags. The =previous reserved parameter (last parameter) has been =eliminated. The returned structure for FIL_STANDARD is now =FILEFINDBUF3 and for FIL_QUERYEASIZE it is FILEFINDBUF4. .Notes =If all shorts are changed to longs, the last arg is Ok .Sample =OS/2 1.3: = HDIR hDir = HDIR_CREATE; = USHORT usCount = 1; = FILEFINDBUF2 FindBuf; = if (!DosFindFirst2 ("C:\\*.*", &hDir, FILE_NORMAL, = &FindBuf, sizeof(FindBuf), &usCount, =: Note that the last arg is a USHORT = FIL_QUERYEASIZE, 0)) = ... =OS/2 2.1: = HDIR hDir = HDIR_CREATE; = ULONG ulCount = 1; = FILEFINDBUF4 FindBuf; = if (!DosFindFirst ("C:\\*.*", &hDir, FILE_NORMAL, = &FindBuf, sizeof(FindBuf), &ulCount, = FIL_QUERYEASIZE)) = ... .Prototyp=APIRET APIENTRY DosFindFirst(PSZ pszFileSpec, PHDIR phdir, = ULONG flAttribute, PVOID pfindbuf, ULONG cbBuf, = PULONG pcFileNames, ULONG ulInfoLevel); .Template=DosFindFirst ($P1,$P2,$P3,$P4,$P5,$P6,$P7) .Command =/* Evaluate and output template */ =SmMigrateKeyword($T1) .Refer =DosFindFirst .Refer =FILEFINDBUF3 .Refer =FILEFINDBUF4 .Refer =$FILEFINDBUF .Refer =$FILEFINDBUF2 You may note that the table code contains a format tag starting with a period in column one. An equal sign appears in column 10 with the data for each element beginning in column 11. If a colon is found in column 11 (first data column) SMART will ignore the record. This can be used for internal comments. The line will appear in SMART View displays. Each input file must contain the table header data at the beginning of the file. Line skips (carriage returns) can be used anywhere in the file to improve readability and should most probably be utilized between keyword definitions to separate keyword data. Navigation Links CONTINUE - Format Tags BACK - Section 1 - UDMD Programming SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2. UDMD - Format Tags ΓòÉΓòÉΓòÉ UDMD - Format tags Format tags are used to identify the coding lines in a Migration table dictionary. The following tags are available for use in a UDMD. .Notice .Table .Version .Date .Keyword .SComment .LComment .Sample .Prototyp .Template .Refer .Command .Notes Navigation Links CONTINUE - Notice Tag BACK - UDMD - Introduction SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.1. Notice Tag ΓòÉΓòÉΓòÉ .Notice Tag .Notice - (Optional) (Max. 79 characters) Notice is simply a comment line and is not processed by SMART. Example: .Notice =Copyright (c) 1993 One Up Corporation, All Rights Reserved Navigation Links CONTINUE - Table Tag BACK - Format Tags FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.2. Table Tag ΓòÉΓòÉΓòÉ .Table Tag .Table - (Required - once at beginning of file) (Max 48 characters) Table specifies the name of the migration table. This is used for display only in the SMART Tables display panel. Example: .Table =OS/2 1.3 to OS/2 2.1 Navigation Links CONTINUE - Version Tag BACK - Notice Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.3. Version Tag ΓòÉΓòÉΓòÉ .Version Tag .Version - (Required - once at beginning of file) (Max 8 characters) Version allows you to specify a version number for the table. This is used for display only in the SMART Tables display panel. Example: .Version =1.0 Navigation Links CONTINUE - Date Tag BACK - Table Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.4. Date Tag ΓòÉΓòÉΓòÉ .Date Tag .Date - (Required - once at beginning of file) (Max 8 characters) Date allows you to specify a creation or modification date for the table. This is used for reference only and appears in the SMART Tables display panel. Example: .Date =12-31-99 Navigation Links CONTINUE - Keyword Tag BACK - Version Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.5. Keyword Tag ΓòÉΓòÉΓòÉ .Keyword Tag .Keyword - (Required at the beginning of a keyword definition data set) The Keyword is a composite data statement consisting of four parameters: Type Code - 3 characters, column 11-13 Category Code - 3 characters, column 15-17 Functional Area Code - 3 characters, column 19-21 Keyword Name - Column 23 (Max 48 Characters) The Type Code, Category Code and Functional Area Code must match the valid codes specified in the companion primary SMART Migration Database. All table records up to the next Keyword data tag will be assigned to the keyword defined in this statement. Example: .Keyword =010 020 130 DosFindFirst2 Navigation Links CONTINUE - SComment Tag BACK - Date Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.6. SComment Tag ΓòÉΓòÉΓòÉ .SComment Tag .SComment - (Required for each keyword - one line only) (Max 120 characters) The Short Comment is a one line comment regarding the migration of the keyword. Example: .SComment=Parameters changed to ULONG and return structure changed Navigation Links CONTINUE - LComment Tag BACK - Keyword Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.7. LComment Tag ΓòÉΓòÉΓòÉ .LComment Tag .LComment - (Required for each keyword ) (Max 120 characters each line) The Long Comment is a single or multi-line comment regarding the migration of the keyword. Note that continued lines do not repeat the tag, but simply require an equal ("=") sign in column 10. The lines should be formatted exactly as you would like to see them appear in the migrated code. Example: .LComment=Parameters changed to ULONG values. Note that the variable =to receive the number of matching entries (addressed by the =6th parameter) has been changed to a ULONG value. =DosFindFirst now includes additional attribute flags. The =previous reserved parameter (last parameter) has been =eliminated. The returned structure for FIL_STANDARD is now =FILEFINDBUF3 and for FIL_QUERYEASIZE it is FILEFINDBUF4. Navigation Links CONTINUE - Sample Tag BACK - SComment Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.8. Sample Tag ΓòÉΓòÉΓòÉ .Sample Tag .Sample - (Optional for each keyword ) (Max 120 characters each line) The Sample is a single or multi-line set of example code regarding the migration of the keyword. Note that continued lines do not repeat the tag, but simply require an equal ("=") sign in column 10. The lines should be formatted exactly as you would like to see them appear in the migrated code. Typically you will want to show an example of the code as it would appear in the source platform code, followed by an example of its use in the target platform. Example: .Sample =OS/2 1.3: = HDIR hDir = HDIR_CREATE; = USHORT usCount = 1; = FILEFINDBUF2 FindBuf; = if (!DosFindFirst2 ("C:\\*.*", &hDir, FILE_NORMAL, = &FindBuf, sizeof(FindBuf), &usCount, = FIL_QUERYEASIZE, 0)) = ... =OS/2 2.1: = HDIR hDir = HDIR_CREATE; = ULONG ulCount = 1; = FILEFINDBUF4 FindBuf; = if (!DosFindFirst ("C:\\*.*", &hDir, FILE_NORMAL, = &FindBuf, sizeof(FindBuf), &ulCount, = FIL_QUERYEASIZE)) = ... Navigation Links CONTINUE - Prototype Tag BACK - LComment Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.9. Prototype Tag ΓòÉΓòÉΓòÉ .Prototype Tag .Prototyp - (Optional for each keyword ) (Max 120 characters each line) The Prototype is a single or multi-line set of code specifying the formal function prototype for the migrated keyword. Note that continued lines do not repeat the tag, but simply require an equal ("=") sign in column 10. The lines should be formatted exactly as you would like to see them appear in the migrated code. Example: .Prototyp=APIRET APIENTRY DosFindFirst(PSZ pszFileSpec, PHDIR phdir, = ULONG flAttribute, PVOID pfindbuf, ULONG cbBuf, = PULONG pcFileNames, ULONG ulInfoLevel); Navigation Links CONTINUE - Template Tag BACK - Sample Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.10. Template Tag ΓòÉΓòÉΓòÉ .Template Tag .Template - (Required for Category 010) (Max 120 characters each line) The Template is the code generating specification for the SMART Migration. In the case of Category 010 Keywords, the Template is the literal replacement string for the migrated keyword. For Category 000, no template is required. In the other categories, templates may be used to assist the SMART user in formatting their own migration. When SMART Migration Command Language (MiCL) is used to create a migration command set the template may be the basis for generating the migration code. Note that continued lines do not repeat the tag, but simply require an equal ("=") sign in column 10. Example: .Template=DosFindFirst ($P1,$P2,$P3,$P4,$P5,$P6,$P7) Navigation Links CONTINUE - Reference Tag BACK - Prototype Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.11. Reference Tag ΓòÉΓòÉΓòÉ .Reference Tag .Refer - (Optional) (Max 120 characters each line) Reference keywords provide hypertext links to items related to the current keyword. The reference items are only used in the SMART Viewer to provide quick access to additional information on related keywords. Only one reference item can be displayed on each .Refer tag line. Any reference with a dollar character ("$") immediately preceding the reference keyword (column 11) indicates that the reference is to an item found elsewhere in the migration table as a keyword. Without the dollar character, SMART View will launch the IBM system View utility to display system help on the keyword topic. Example: .Refer =DosAllocMem .Refer =DosAllocSharedMem .Refer =$GlobalAlloc .Refer =$GlobalLock Navigation Links CONTINUE - Command Tag BACK - Template Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.12. Command Tag ΓòÉΓòÉΓòÉ .Command Tag .Command - (Optional) (Max 120 characters each line) The Command is a set of SMART Migration Commands described elsewhere in this document. See Section 2 - MiCL Programming Any Category of Keywords can have command statements, but they are typically used for Category 020 and 030 Keywords in the manipulation of templates for migration code generation. In the absence of Command statements the default migration will prevail. This is: Comments only for Category 000; Literal replacement of the keyword by the template for Category 010; and insertion of comments, templates and other data elements in the other categories as specified by the Category Format Options selected by the user. The Command statements control the migration generated for the Keyword, however and Short or Long Comments, Prototypes, and Sample code will automatically be inserted in the migrated code unless omitted by a "SmNoComment" command in this data set. Note that continued lines do not repeat the tag, but simply require an equal ("=") sign in column 10. Example: .Command =/* Evaluate and output template */ =SmMigrateKeyword($T1) Navigation Links CONTINUE - Notes Tag BACK - Reference Tag FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.13. Notes Tag ΓòÉΓòÉΓòÉ .Notes Tag .Notes - (Optional) (Max 120 characters each line) Notes are used to insert a set of coding lines in the Migration table for explanation or clarification to the UDMD developer and is not used SMART processing. Notes will not be displayed in SMART Viewer. You may also us a colon (":") in any coding line except for the table heading data ( .Table, .Version, .Date, and .Notice) to indicate a comment to the developer. SMART will not process the comment, however the comment will display in SMART Viewer. Continued lines do not repeat the tag, but simply require an equal ("=") sign in column 10. Example: .Notes =This migration assumes that all shorts have been changed to longs. =If not, care must be taken to properly type cast the argument variables. Navigation Links CONTINUE - UDMD Programming Notes BACK - Command Tags FORMAT TAGS SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 4.2.14. UDMD Programming Notes ΓòÉΓòÉΓòÉ .UDMD Programming Notes The use of the User Defined Migration Database is effective in overriding the SMART Migration Database for specific keywords to customize the migration and analysis to meet the specific requirements of your code. For example, you may wish to port all USHORT, SHORT and int variable types to ULONG and LONG. You may also replace the use of NULL with simply 0. If you are using Common Functions, you may also wish to change all occurrences of those function calls that are replaced by the Common Functions that you have created. All of these custom changes can be performed by a few simple lines of code in a User Defined Migration Database. Since the System provided SMART Migration Databases were constructed to handle the general cases, you may increase the effective automatic migration of your source code and greatly reduce your migration effort by the creative use of your own UDMD. Navigation Links CONTINUE - Section 2 - MiCL Programming BACK - Notes Tag SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 5. Section 2 - MiCL Programming ΓòÉΓòÉΓòÉ Migration Command Language Programming Introduction General Language Description Variables and Constants Strings and Quotations SMART Built-in Functions MiCL Instructions Event Command Procedures Programming Notes and Tips Navigation Links CONTINUE - MiCL Introduction BACK - UDMD Programming Notes SECTION 1 - UDMD Programming CONTENTS ΓòÉΓòÉΓòÉ 5.1. MiCL Introduction ΓòÉΓòÉΓòÉ MiCL Programming Introduction SMART Version 1.0 was limited to migration changes that are straight forward and require only literal string changes. All of the remaining changes that are required to be made are flagged in the source code with migration comments and left to the developer to complete. This provides a great deal of help in the migration effort but is limited in this rather closed solution. The SMART Migration Command Processor Language defined in this document, when implemented within SMART, will create a flexible, open and VERY powerful migration environment. Essentially the SMART migration process can be programmed with this language. The migration of each keyword can be programmed with context sensitive logical statements; generating migration source code specific to the requirements of each individual keyword encounter. Furthermore, SMART takes on expert characteristics. With appropriate programming of the keyword commands, recurring data can be stored and reused upon subsequent encounters of the same migration instance. The command set has the capability of prompting the user for required parameters and storing the parameter for continuing use in the migration of individual keywords. The data obtained during a migration run can be saved in simple ASCII text format and modified for reuse in following runs. In addition to command sets processed for assigned keywords, command sets can be programmed to execute at specific migration events, such as: pre and post migration run, pre and post file, at the encounter of a function definition, and so on. The interactive features of this command language allow the migration developer to customize the migration process, pausing at times during the process, displaying specific lines of source code and allowing the user to respond to questions from the migration command processor. The SMART user can create their own migration database, or override the SMART migration database for any desired keyword. The user can add and modify migration commands, customizing the migration process to take advantage of their specific migration requirements. This migration language is intentionally designed to conform closely to the Rexx Macro Language syntax. However, the implementation contains only a very small subset of the Rexx capabilities and has NO interface to the Rexx Command Processor. You may also take care to note the differences between the Rexx programming language syntax and that of SMART MiCL. This document describes the capabilities and syntax of the SMART Migration Command Language. The following topics are covered: General Language Description Variables and Constants Strings and quotations SMART Built-In Functions Instructions Other Language & Command Processor Characteristics - Pre and Post Command Procedures Programming Notes, Tips & Sample Code Navigation Links CONTINUE - General Language Description BACK - Section 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.2. General Language Description ΓòÉΓòÉΓòÉ General Language Description The SMART Migration Command Language is Rexx-like in syntax. All data is stored as character strings, eliminating the requirement for data declarations. Each command set is processed after a SMART Migration event - typically after the detection of a keyword in the source code stream. As such, predefined variables contain many of the parameters, arguments, and conditions encountered in the detection of the migration keyword. The instructions are limited to the following set: 1. Assignment MyVariable = "HWND" 2. Execution of a SMART built-in functions rtn = SmPrompt ( "Enter variable for HAB:", "hab", BUTTON, ENTRY, OK | CANCEL ) 3. Comparison instructions IF $LCNT > "2" THEN EXIT Included in this instruction set are IF, THEN, ELSE, DO-END, along with comparison operator =, <, >, and NOT. Any number of comments can be embedded in the SMART command set and must be contained within the delimiters /* and */. MiCL Language statements cannot be continued on multiple lines except for built-in function arguments (bounded by parentheses) and the code between the "IF-THEN" comparison instruction. Built-in Function arguments cannot, however, span multiple lines if the function is the object of an IF-THEN comparison. Navigation Links CONTINUE - Variables and Constants BACK - MiCL Introduction SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.3. Variables and Constants ΓòÉΓòÉΓòÉ Variables and Constants Predefined Variables The SMART Migration Language Command Processor predefines a number of variables available to the user for each keyword command set. All predefined variables start with a dollar sign ($). The following list describes these variables: $KEY Contains the keyword string. $KCAT Contains the three character key for the keyword Category, i.e. 020. $KTYPE Contains the three character key for the keyword Type. $KAREA Contains the three character key for the keyword Functional Area. $KIND Contains the condition of the keyword's autonomy - TRUE (1) is a stand-alone keyword statement, 0 or FALSE is an embedded keyword. $KRTN If the current keyword is preceeded by an equal sign, the variable preceding the equal sign is stored with this identifier. $P1 - $P99 Contains the argument string of an API keyword. $PCNT Contains a value for the number of arguments for an API Keyword. $TCNT Contains a value for the number of Templates provided for this keyword. $T1 - $T99 Contains the template strings for a specific keyword. $LFILE Contains the fully qualified filename of the current keyword encounter. $LLINE Contains the line number of the current keyword encounter. $LCOL Contains the current column starting position of the current keyword encounter. .$LCNT Contains the number of source code lines in the current parsed code block. $Gxxxxxxxx Contains global data assigned by the user and available by any keyword in any occurrence. The "xxxxxxxx" is a user defined 8 character identifier. $Sxxxxxxxx Contains keyword, static, local data assigned by the user and available for every occurrence of the same keyword occurrence in the current processing run. The "xxxxxxxx" is a user defined 8 character identifier. User defined variables When you choose a name for a variable, the first character must be one of: A B C...Z ! ? _ or $ (if the variable is Static or Global) Lowercase letters are also allowed as a first letter and are converted to uppercase. The rest of the characters can be any of the preceding characters ( except for $) and also 0 through 9. All text not in quotations is converted to uppercase prior to processing. All variables are initialized as null character strings. (This deviates from the REXX standard). Single character variables can not be used. Do not define variables beginning with $K, $L, $P, $T - as these variables are designated for system use only. User defined, keyword local variables beginning with "?" can be evaluated in template evaluation. Variables beginning with $G and $S are designated for use as Process Global and Keyword Static variables. Constants Numeric constants cannot be used in this version of MiCL. Where needed use the literal equivalent of the number string. As an example: IF $LCNT > "1" THEN EXIT Related Topics Preset Variables Global, Static and Local Variables String and Variable Evaluation Navigation Links CONTINUE - Strings and Quotations BACK - Language Description SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.4. Strings and Quotations ΓòÉΓòÉΓòÉ Strings and Quotations A string is any group of characters inside single or double quotation marks. Either type of quotation marks can be used, but the beginning and the ending mark must match. The command processor stops processing the quotation when a quotation mark and the characters that follow remain as they were typed, with uppercase and lowercase letters. The command processor resumes interpreting when it sees a matching quotation mark. For example: 'CreateWindow' "CreateWindow" are both strings in quotation. To use an apostrophe (single quotation mark) or double quotation marks within a string, use the other quotation mark around the whole string. For example: 'The keyword is "CreateWindow"' or "The keyword is 'CreateWindow'" You also can use a pair of quotation marks (the same as those used to mark the string). However, the double quotation marks may not be the first marks of a quotation. If an open quotation mark is immediately followed by another quotation mark of the same type it will be interpreted as a null string in quotation. An example of properly used nest quotation follows: "Error Condition. ""Can't find template.""" This is interpreted by the command processor as: Error Condition. "Can't find template." A nested quotation can be expressed as follows: "'This string is in quotation.'" The preceding example is evaluated as follows: 'This string is in quotation.' A literal string can be formatted by using a series of literal constants and/or variables in an assignment instruction: ASTRING = "The first parameter is: " $P1 In this example, if the first parameter was "hWindow" the value of MYSTRING will be: The first parameter is: hWindow Each segment of the assignment is concatenated to the next. Be careful to insert spaces in quotation where spacing may be required. Note that the variable $P1 was placed outside the quotation marks. If the variable had been placed within the quotation marks the variable would have been assumed to be part of the literal string and not evaluated for the expression. Variables are not evaluated when they are placed in quotation. The template is a special string. It should not be specified with bounding quotation marks when entered into the migration dictionary with the ".Templete" tag. When evaluated by the SmMigrateKeyword, SmSendToEditor, or SmOutputLine function, the only variables that are replaced by the value of the variables are SMART predefined variables, global and keyword static variables or user defined local variables beginning with "?" (question mark). Variables placed within quotation marks are not evaluated. During this evaluation, all spacing is maintained in the evaluated expression (blanks are retained). This differs from expression evaluation with the assignment operator (=). In expression evaluation for assignment, all variables not in quotation, are replaced by their stored values and all items evaluated are concatenated in the output string. Spaces not in quotation or part of an evaluated variable are ignored. Related Topics Use of Templates String and Variable Evaluation Navigation Links CONTINUE - Built-In Functions BACK - Variables and Constants SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5. SMART Built-in Functions ΓòÉΓòÉΓòÉ SMART Built-in Functions There are a number of SMART functions that are callable from within the SMART Migration Command Language. The functions are "C" Language-like in syntax with the function name followed by the function argument, enclosed in parenthesis and separated by commas. The success value of the function call will be the returned and can be assigned to a user defined variable when the function is called. These functions include the following: SmDisplayDlg( ) SmGetListName( ) SmGetListPath( ) SmGetSmartPath( ) SmIgnoreKeyword( ) SmListDlg( ) SmLoadVars( ) SmMigrateKeyword( ) SmNoComment( ) SmNoMigrate( ) SmOutputLine( ) SmOutputNote( ) SmPromptDlg( ) SmRemove( ) SmSaveVars( ) SmSendToEditor( ) Navigation Links CONTINUE - SmDisplayDlg( ) BACK - Strings and Quotations SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.1. SmDisplayDlg( ) ΓòÉΓòÉΓòÉ .SmDisplayDlg( ) SmDisplayDlg ( Display_String, Option_Return, Control_Options ) SmDisplayDlg creates a popup dialog to display a message string. Processing will be halted and the dialog will remain displayed until the user presses one of the control option buttons. Up to four programmable push-buttons can be defined in this call. Accelerators can be assigned to the push-buttons by using the tilde (~) character preceding the push-button display character of the desired accelerator key. The value of the returned option selected by the user will not contain this tilde character. Description for the arguments of this function follows: Display_String The user supplied literal string to display (up to 80 characters). This argument can also be a variable whose value contains the string to display. Option_Return A variable to contain the literal value of the button selected by the user to terminate the display (see Control_Options). Control_Options Up to four strings representing the identification of the push-buttons to appear on the display. The buttons will appear in the order as they appear in this argument. Each button ID must be separated by the "|" character. Upper and lower case, along with the aforementioned tilde can be used. By default the first button responds to the "Enter" key, and the second button responds to the "ESCape" key. result A success value for the function. 1= Ok. 0=Error. Example: RTN = SmDisplayDlg("Verify Processing this Keyword", OPTION, ~Ok | ~Cancel | ~Abort ) IF OPTION = "ABORT" THEN TERMINATE Notes: The position of the Display Dialog on the user desktop is saved at the termination of the dialog. The user can move the dialog panel to a convenient position. Subsequent dialog displays from this function call will appear in the same position. This dialog can be used to suspend processing while displaying the source code at the current keyword encounter from the use of the SmSendToEditor command function. Related Topics Use of Dialog Functions Launching the Editor Navigation Links CONTINUE - SmGetListName BACK - Built-In Functions SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.2. SmGetListName( ) ΓòÉΓòÉΓòÉ .SmGetListName( ) SmGetListName ( Return_Variable ) SmGetListName returns the fully qualified filename of the current List-of-Files used in the migration process. Description for the arguments of this function follows: Return_Variable A variable to contain the filename of the List-of-Files. result A success value for the function. 1= Ok. 0=Error. Example: SmGetListName( LISTNAME ) IF LISTNAME = "C:\MYAPP\LIST.LST" THEN SmLoadVars( "C:\MYAPP\VARS1.DAT" ) ELSE SmLoadVars( "C:\MYAPP\VARS2.DAT" ) Navigation Links CONTINUE - SmGetListPath BACK - SmDisplayDlg BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.3. SmGetListPath( ) ΓòÉΓòÉΓòÉ .SmGetListPath( ) SmGetListPath ( Return_Variable ) SmGetListPath returns the directory path of the current List-of-Files used in the migration process. Description for the arguments of this function follows: Return_Variable A variable to contain the path of the List-of-Files. result A success value for the function. 1= Ok. 0=Error. Example: SmGetListPath( LISTPATH ) VARNAME = LISTPATH "\VARS.DAT" SmLoadVars( VARNAME ) Navigation Links CONTINUE - SmGetSmartPath BACK - SmGetListName BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.4. SmGetSmartPath( ) ΓòÉΓòÉΓòÉ .SmGetSmartPath( ) SmGetSmartPath ( Return_Variable ) SmGetSmartPath returns the directory path of the SMART application executable. Description for the arguments of this function follows: Return_Variable A variable to contain the path of the SMART executable. result A success value for the function. 1= Ok. 0=Error. Example: SmGetSmartPath( SMARTPATH ) VARNAME = SMARTPATH "\DATA\VARS.DAT" SmLoadVars( VARNAME ) Navigation Links CONTINUE - SmIgnoreKeyword BACK - SmGetListPath BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.5. SmIgnoreKeyword( ) ΓòÉΓòÉΓòÉ .SmIgnoreKeyword( ) SmIgnoreKeyword ( ) SmIgnoreKeyword excludes processing of the current keyword. This is equivalent to entering the keyword in an exclude list for processing. However, since this command appears in the MiCL Language, it can be dynamically and interactively applied. No comments for this keyword will appear in the migrated output file. See also: SmNoMigrate and DEFAULT. Description for the arguments of this function follows: result A success value for the function. 1= Ok. 0=Error. Example: IF $SIgnore = "" THEN DO STRING = "Verify Ignore Keyword on all: " $KEY SmDisplay( STRING, $SIgnore, ~Yes | ~NO | ~Abort) END IF $SIgnore = "Abort" THEN TERMINATE IF $SIgnore = "Yes" THEN SmIgnoreKeyword( ) ... Notes: Note in the example a static variable was defined to contain the user response to the question of ignoring the current keyword. Upon subsequent encounters this variable will contain "Yes" or "No" and the display is not required. If this static variable is saved at the end of the process and reloaded at the beginning of other process runs, then this variable will always respond to the initial user query. By using SmSendToEditor followed by SmDisplayDlg you can allow the user to view each encounter of the keyword and enter the appropriate response for ignoring the keyword or not ignoring the keyword for migration. Related Topics Migration Control SmNoMigrate Navigation Links CONTINUE - SmListDlg BACK - SmGetSmartPath BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.6. SmListDlg( ) ΓòÉΓòÉΓòÉ .SmListDlg( ) SmListDlg ( Display_String, Edit_String, Option_Return, String_Return_Variable, Filename) SmListDlg creates a popup dialog to provide a list of options to select or maintain. This is ideal for interactive processing where a user can select from a list of templates or processing options. The user will also have the opportunity to add new items to the list. The list of items is stored and retrieved as a text file with the designated filename in the argument of this function call. The response buttons on this dialog are fixed, but both the button name and the selected string will be returned to the variables as specified by the arguments of this call. Processing will be halted and the dialog will remain displayed until the user presses one of the control option buttons. Description for the arguments of this function follows: Display_String The literal string to display (up to 80 characters) above the list box. This argument can also be a variable that contains the string to display. Edit_String The default edit string that will be displayed and highlighted above the list box. Option_Return A variable to contain the literal value of the button selected by the user to terminate the display. "Process", "Cancel", "Store" or "Terminate" is valid. String_Return_Variable A Variable to contain the list box selection if the user terminates with "Process". Filename The filename to contain the text items to display in the listbox. If the user terminates the dialog with "Process" or "Store", the items contained in the current list box, including any changes will be stored in the designated filename. result A success value for the function. 1= Ok. 0=Error. Example: SmSendToEditor( "$LFile($LLine:$LCol)R" ) SmListDlg("Select the choice for HANDLE replacement", $Shandle, OPTION, $Shandle, "HANDLE.DAT" ) IF OPTION = "Terminate" THEN TERMINATE IF OPTION = "Cancel" THEN EXIT IF OPTION = "Store" THEN EXIT SmMigrateKeyword( $Shandle ) Notes: The position of the List Dialog on the user desktop is saved at the termination of the dialog. The user can move the dialog panel to a convenient position. Subsequent displays of this dialog will appear in the same position. This dialog can be used to suspend processing while displaying the source code at the current keyword encounter from the use of the SmSendToEditor command function. If the filename containing the list to display does not exist, the user will be advised and can proceed by creating a new file with their own entries, or canceling this step. The advantage of this dialog is that the user can easily select an existing item in the list, or modify the list. The list will be saved (upon appropriate termination of the dialog) and the stored items will appear in subsequent encounters of the keyword. Note the use of the static variable $Shandle in the example above. By using this variable as both the Edit_String and the String_Return_Variable arguments, the selected string returned by the user will appear as the default option in the next encounter. Also note the use of SmSendToEditor. In this example the source code at the point of encounter was displayed to allow the user to see the keyword in context before making a listbox selection. The filename specified in this function call does not require a fully qualified path if the file is located in the same directory as the List-of-Files file for the migration process. The path for the List-of-Files or the main SMART directory path can be obtained by appropriate built-in function calls. Related Topics Use of Dialog Functions Launching the Editor Navigation Links CONTINUE - SmLoadVars BACK - SmIngoreKeyword BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.7. SmLoadVars( ) ΓòÉΓòÉΓòÉ .SmLoadVars( ) SmLoadVars ( Filename ) SmLoadVariables reads the ASCII text file specified by filename to assign values to global and keyword static variables. The file can be created using a text editor or can be the stored result of the SmSaveVars function call. Description for the arguments of this function follows: Filename The filename of the output file. If the filename is not fully qualified, the default directory is the directory containing the currently selected List-Of-files. result A success value for the function. 1= Ok. 0=Error. Example: SmLoadVars ( "VARS1.DAT" ) Notes: Each line of the file containing the stored variables and their values must contain an assignment statement of the form: $Gvariable = value (for Process Global variables) or Keyword.$Svariable=value (for Keyword Static variables) For example: $Ghab=hab WinCreateMessage.$Shandle=hwnd Note in the case of keyword static variables, the variable is keyword identified by preceding the variable name with the keyword followed by a period (.). The keyword in this case is case sensitive an should appear exactly as it is coded in the migration database. This call is best utilized by including this function in a preprocess command set ($$PRE_PROCESS) with the companion call, SmSaveVars, performed as a part of the $$POST_PROCESS command set. This effectively restores and saves all global and keyword static variable values. Related Topics Pre and Post Command Sets Navigation Links CONTINUE - SmMigrateKeyword BACK - SmListDlg BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.8. SmMigrateKeyword( ) ΓòÉΓòÉΓòÉ .SmMigrateKeyword( ) SmMigrateKeyword ( Template ) The SmMigrateKeyword command replaces the current keyword with the argument of this command. If the keyword is an API keyword, then this output will replace both the keyword and all arguments of the API call including the opening and closing parentheses. Typically this argument will be a template for the keyword. However it can be a literal string formatted in this command set. The argument can consist of a single variable or literal string. This command MUST appear in each command set unless the keyword is to remain, blank, or the SmRemove command is used to remove source code related to the keyword. Failure to do so will result in a NULL output in the migrated source code. Description for the arguments of this function follows: Template A variable containing a keyword template, or a variable containing a string to be processed as a template, or a literal to be used as a template. result A success value for the function. 1= Ok. 0=Error. Example: NEWTEMPLATE = "WinQueryWindow( $P1, QW_PARENT)" SmMigrateKeyword( NEWTEMPLATE ) Notes: Note that the argument of the SmMigrateKeyword is evaluated as a template. Only $variables and ?variables are replaced with their values and all spacing will remain intact. Only ONE call to SmMigrateKeyword should be made while processing a keyword encounter. If multiple calls are made, only the last call will create the migration code. DO NOT include a semicolon at the end of an API template to be used in this function. The keyword may be an embedded argument of a higher API call and not require a semicolon. Note that in the case of an API keyword, both the keyword string and ALL arguments including the bounding parentheses are replaced by the argument of this function call. If multiple lines are to be output in the migration you must use this function call, or SmRemove, along with the SmOutputLine function. Related Topics Preset Variables Use of Templates Migration Control Migration Notes and Comments String and Variable Evaluation Navigation Links CONTINUE - SmNoComment BACK - SmLoadVars BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.9. SmNoComment( ) ΓòÉΓòÉΓòÉ .SmNoComment( ) SmNoComment ( param1 | [ param2 | ... ] ) SmNoComment turns off the designated migration comments for this encounter of the current keyword only. Description for the arguments of this function follows: param The following parameters are valid for this call: LCOMMENT, SCOMMENT, SAMPLE, PROTOTYPE, TEMPLATE ALL (All comments). When specifying multiple parameters use the "|" character to separate each parameter. result A success value for the function. 1= Ok. 0=Error. Example: SmNoComment( LCOMMENT | SAMPLE | PROTOTYPE | TEMPLATE ) Notes: Please note the interaction and capabilities of the SmIgnoreKeyword, SmNoMigrate, and SmNoComment commands. SmIgnoreKeyword acts if the keyword did not exist in the migration table - no processing is performed on this keyword. SmNoMigrate causes no change in the migrated output code, but retains any comments that you may wish to insert in the output code. These comments can be modified by using the SmNoComment command turning off any or all migration comments, and by using the SmOutputNote to insert custom comments in the output code. Related Topics Migration Notes and Comments Navigation Links CONTINUE - SmNoMigrate BACK - SmMigrateKeyword BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.10. SmNoMigrate( ) ΓòÉΓòÉΓòÉ .SmNoMigrate( ) SmNoMigrate ( ) SmNoMigrate suspends any migration processing for the current keyword instance. The output will look just like the input. However, all comments scheduled to be inserted in the output source code will be processed. (In the SmIgnoreKeyword call, the keyword processing is completely ignored). In combination with SmNoComment(ALL) the migration for this keyword will be ignored. You may use SmNoMigrate with SmNoComment and SmOutputNote to insert a processing note at the point of this keyword encounter. Description for the arguments of this function follows: arguments None. result A success value for the function. 1= Ok. 0=Error. Example 1: SmNoMigrate( ) SmNoComment( ALL ) NOTE = "Keyword: " $KEY must be reworked for complete migration." SmOutputNote( NOTE ) Example 2: OPTION = "" SmNoComment(ALL) IF $Scontrol NOT = "No Verify" THEN SmSendToEditor( "$LFile($LLine:$LCol)R" ) IF $Sreplaced = "" THEN DO PROMPT = "Enter replacement string for: " $KEY SmPromptDlg(PROMPT, "", OPTION, $Sreplaced, ~Ok | ~Abort ) END IF OPTION = "Abort" THEN TERMINATE IF $Sverify = "No Verify" THEN DO DISPLAY = "Verify replacement of: " $KEY " by " $Sreplaced SmDisplayDlg(DISPLAY, $Scontrol, ~Yes | ~NO | No ~Verify | ~Abort) END IF $Scontrol = "Abort" THEN TERMINATE IF $Scontrol = "No" THEN DO SmNoMigrate( ) EXIT END ELSE SmMigrateKeyword( $Sreplaced ) Notes: Example 2 is a search and replace with initial replacement prompt and a verify for each encounter. If "No Verify" is selected, the process will automatically perform the replacement without any notification. Related Topics Migration Control Navigation Links CONTINUE - SmOutputLine BACK - SmNoComment BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.11. SmOutputLine( ) ΓòÉΓòÉΓòÉ .SmOutputLine ( ) SmOutputLine ( Template ) The SmOutputLine command is similar to SmMigrateKeyword , except that this command is used to generate additional output lines (following the migration). This command is useful to generate multiple lines of migration code in Category 030 migration encounters, or where program code or comments are to be required to be placed in the output. This function is different from SmOutputNote . The generated code will not be in comments and will appear in the output stream immediately following the code block containing the encountered keyword. The argument for this function can be a variable or a literal string. The value of the argument will be evaluated (if not a literal string) by replacing all variables beginning with "$" (dollar sign) or "?" (question mark). Any variable referenced but not defined will be replaced by a null character. Description for the arguments of this function follows: Template A variable containing a keyword template, or a variable containing a string to be processed as a template, or a literal to be used as a template. result A success value for the function. 1= Ok. 0=Error. Example 1: SmNoMigrate( ) SmNoComment( ALL ) NOTE = "Keyword: " $KEY must be reworked for complete migration." SmOutputNote( NOTE ) Example 2: IF $KIND = "TRUE" THEN DO SmMigrateKeyword( $T1 ) SmOutputLine( $T2 ) END ELSE ... Notes: If the migrating keyword is embedded in the arguments of a higher level function call a comment will be generated in the output code and the additional output line will be supressed. If the keyword is within an 'if', 'while', or 'for' statement as a single API function call, braces will be added, if required, to insure that all of the generated lines are properly placed within the scope of the statement. Note that the Keyword Independent Flag "$KIND" contains a literal value of "TRUE" or "FALSE". When creating the template or literal string for each of the generated additional lines of code, remember that a keyword is not being replaced by the code line, but instead the line is placed in full in the output stream. As such, a semicolon at the end of the line may be necessary to terminate a statement. Related Topics Use of Templates Migration Control Migration Notes and Comments String and Variable Evaluation Navigation Links CONTINUE - SmOutputNote BACK - SmNoMigrate BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.12. SmOutputNote( ) ΓòÉΓòÉΓòÉ .SmOutputNote ( ) SmOutputNote ( Line ) SmOutputNote places a string in the output migration comments. This comment is tagged as "SM$:I". This argument should be limited to a maximum of 80 characters for each note line created. Description for the arguments of this function follows: Line Variable containing an note line or a literal string. result A success value for the function. 1= Ok. 0=Error. Example: NOTE = "Keyword is embedded and cannot be properly migrated: " $KEY SmOutputNote ( NOTE ) ... Notes: Any notes generated in the output code will be appropriately placed in comments along with the other migration comments. Suppression of migration comments with the SmNoComment command will not affect the generation of notes created with this built-in function call. It is helpful to identify the keyword that is the object of the note to insure that the user clearly understands which keyword the generated comment is associated. Related Topics Migration Notes and Comments Navigation Links CONTINUE - SmPromptDlg BACK - SmOutputLine BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.13. SmPromptDlg( ) ΓòÉΓòÉΓòÉ .SmPromptDlg ( ) SmPromptDlg ( Display_String, Edit_String, Option_Return, String_Return_Variable, Control_Options) SmPromptDlg creates a popup dialog and waits for a user response. This dialog is useful for obtaining variable names from the user at run time. Up to four programmable push-buttons can be defined in this call. Accelerators can be assigned to the push-buttons by using the tilde (~) character preceding the push-button display character of the desired accelerator key. The value of the returned option selected by the user will not contain this tilde character. Description for the arguments of this function follows: Display_String The user supplied literal string to display (up to 80 characters). This argument can also be a variable that contains the string to display. Edit_String The default edit string that will be displayed and highlighted in he entry panel ready for change. Option_Return A variable to contain the literal value of the button selected by the user to terminate the display (see Control_Options). String_Return_Variable A variable to contain the value of the entry field upon termination of the dialog. This will contain the user entry to the prompt of this dialog. Control_Options Up to four strings representing the identification of the push-buttons to appear on the display. The buttons will appear in the order as they appear in this argument. Each button ID must be separated by the "|" character. Upper and lower case, along with the aforementioned tilde can be used. By default the first button responds to the "Enter" key, and the second button responds to the "ESCape" key. result A success value for the function. 1= Ok. 0=Error. Example: IF $Shab = "" THEN $Shab = "hab" RTN = SmPromptDlg("Please enter the variable name used for HAB", $Shab, OPTION, $Shab, ~Ok | ~Cancel | ~Abort ) IF OPTION = "ABORT" THEN TERMINATE Notes: The position of the Prompt Dialog on the user desktop is saved at the termination of the dialog. The user can move the dialog panel to a convenient position. Subsequent displays of this dialog type will appear in the same position. The use of a single keyword static variable for both the Edit_String and the String_Return_Variable give the user his previous entry as the initial default. Related Topics Use of Dialog Functions Launching the Editor Navigation Links CONTINUE - SmRemove BACK - SmOutputNote BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.14. SmRemove( ) ΓòÉΓòÉΓòÉ .SmRemove ( ) SmRemove ( Option ) SmRemove will remove either the keyword, the source code line in which the keyword is found or the complete statement block at has been parsed as part of the keyword statement. The value of the options argument specifies 'KEYWORD', 'LINE', or 'BLOCK'. Due to the complexity of the coding syntax that may occur in the source code, it is advised that the user have the opportunity to view the context of the keyword to determine if the removal is appropriate. Description for the arguments of this function follows: Option 'KEYWORD', 'LINE', or 'BLOCK'. result A success value for the function. 1= Ok. 0=Error. Example: SmSendToEditor( "$LFile($LLine:$LCol)R" ) DISPLAY = "Choose Removal Option for: " $KEY SmDisplayDlg( DISPLAY, OPTION, ~Line | ~Cancel | ~Keyword | ~Block) IF OPTION = "Cancel" THEN DO SmNoMigrate() EXIT END ELSE SmRemove( OPTION ) Notes: You can use SmRemove along with SmOutputLine to replace source code with newly generated output code. Using SmRemove with the "KEYWORD" option replaces the keyword. (and any arguments, if the keyword is a API function) with a null string. Note however that the code surrounding the keyword remains intact (including a terminating semicolon if it appears). A stand alone API function call should by removed with the "LINE" option to insure that the termination semicolon is properly erased in the output. Related Topics Migration Control Navigation Links CONTINUE - SmSaveVars BACK - SmPromptDlg BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.15. SmSaveVars( ) ΓòÉΓòÉΓòÉ .SmSaveVars ( ) SmSaveVars ( Filename, Options ) SmSaveVars creates an ASCII text file containing assignment statements with the variables and values of these variables that the time that this function is executed. The format of the file corresponds to the format described above for SmLoadVars. The Options argument specifies whether GLOBAL, STATIC or both sets of variables are to be written to the file. This command is usually performed at the end of the process in the "$$POST_PROCESS" command procedure. Description for the arguments of this function follows: Filename The filename of the output file. If the filename is not fully qualified, the default directory is the directory containing the currently selected List-Of-Files. Options Specify the type of variables and can be one or a combination of the following ( separated by the OR symbol, "|" ): GLOBAL' - process global variables and/or 'STATIC' - keyword static variables result A success value for the function. 1= Ok. 0=Error. Example: SmSaveVars( "VARS1.DAT", GLOBAL | STATIC ) Related Topics Pre and Post Command Sets Global, Static and Local Variables Navigation Links CONTINUE - SmSendToEditor BACK - SmRemove BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.5.16. SmSendToEditor( ) ΓòÉΓòÉΓòÉ .SmSendToEditor ( ) SmSendToEditor ( Template ) SmSendToEditor passes the Parameter to the editor defined in the SMART setup options. The editor, or whatever proxy program is specified in the setup option, will be spawned by this command. The argument in this command will be passed as an argument string to the application spawned. If you want to pause processing at this point until the user has a chance to view the displayed argument, you should follow this command with the SmDisplayDlg, SmPromptDlg, or SmListDlg command. Typically, the argument for an editor will be the filename, linenumber, column of the current keyword. Failure to temporarily halt the processing while the editor is receiving the parameter from this command may create a race condition with multiple commands in rapid fire succession attempting to display multiple files. The timing of this condition may create a system wide failure, if not just a mess of confused editor instances and file displays. The use of a project ID is highly recommended in the creation of a The SMART Editor instance for SMART, and in the parameter of the SMART Editor specification. Description for the arguments of this function follows: Template A variable containing a keyword template, or a variable containing a string to be processed as a template, or a literal to be used as the argument in starting the SMART specified editor (see "Options", "SetupOptions" in the main menu of SMART.) Note that if other parameters are specified in the Setup Panel, they will be sent in addition to the argument of this command. result A success value for the function. 1= Ok. 0=Error. Example: SmSendToEditor( "$LFile($LLine:$LCol)R" ) DISPLAY = "Migrate This Keyword : " $KEY SmDisplayDlg( DISPLAY, OPTION, ~Yes | ~No | ~Abort) IF OPTION = "Abort" THEN TERMINATE IF OPTION = "NO" THEN SmNoMigrate() ELSE SmMigrateKeyword( $T1) Notes: The construction of the parameter to send to the editor maybe somewhat dependent upon the capabilities of the editor. In the above example the created parameter will appear in the following format indicating a fully qualified file name followed by line and column number of the keyword, and a designator for opening the file as read-only: C:\MYAPP\FILE.C(123:12)R Related Topics Use of Templates Use of Dialog Functions Launching the Editor Navigation Links CONTINUE - MiCL Instructions BACK - SmSaveVars BUILT-IN FUNCTIONS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.6. MiCL Instructions ΓòÉΓòÉΓòÉ MiCL Instructions The following processing instructions are defined in the SMART Migration Command Language. IF - THEN ELSE DO-END EXIT DEFAULT TERMINATE = (Assignment) In addition to the instructions, the following comparison operators are defined to be used in the decision instruction, IF-THEN. < (Less than) > (Greater than). = (Equal) NOT ( used in conjunction with one of the other operators) IF - THEN - ELSE- DO - END The "IF" instruction is used with a "THEN" instruction to make a decision. The command processor runs the instruction if the expression is true; for example: if answer = "YES" then EXIT In this example, the EXIT instruction is processed only if "answer" has the value of "YES". Character strings are compared character by character with a result of true or false depending upon the ASCII value of the first non-matching character. You can group instructions using DO and END . To tell the interpreter to run a list of instructions after the THEN instruction, use DO-END as in the following example: if answer = "YES" then DO ... ... ... END else ... The DO and its END instruction tell the interpreter to process any instructions between them depending upon the comparison condition. ELSE identifies the instruction to be run if the expression is false. To tell the interpreter to select from one of two possible instructions, use: IF expression THEN instruction1 ELSE instruction2 You could include the IF-THEN-ELSE format in a procedure like this: IF answer = 'NO' THEN EXIT ELSE SmMigrateKeyword( $T1 ) The comparison operators (<,>,=) along with the NOT operators can be used in combination with the decision instruction (IF). Nested IF statements are only allowed if the scope of each nested if instruction is defined by the DO-END instruction set. As an example: IF OptionA = "TRUE" THEN DO IF OptionC = "TRUE" THEN DO SmDisplayDlg("OptionC is TRUE", OPTION, Ok | Cancel | Abort) EXIT END ELSE SmDisplayDlg("OptionC is FALSE", OPTION, Ok | Cancel | Abort) END ELSE DO SmDisplayDlg("OptionA is FALSE", OPTION, Ok | Cancel | Abort) IF OptionB = "TRUE" THEN SmDisplayDlg("OptionB is TRUE", OPTION, Ok | Cancel | Abort) ELSE SmDisplayDlg("OptionB is FALSE", OPTION, Ok | Cancel | Abort) END The "IF" instruction must appear as the first word on a command coding line. Processing for the comparison statement stops with the "THEN" instruction. The "DO" and "END" instructions must appear on separate coding lines without any other instruction. The comparison expression in an IF-THEN instruction can only be a simple statement of the form: item1 operator item2 Where: item1 must be a variable operator can be "<", ">", or "=" and may be preceeded by "NOT" item2 must be a variable, or a literal string. Example: if OPTION = 'Abort' then TERMINATE if RESULT not = "Ok" then EXIT EXIT The EXIT instruction terminates processing of the current command set. The EXIT statement is not required at the end of the command set, since an exit condition is processed by default at the end of each command set. DEFAULT The DEFAULT instruction exits the current MiCL command set and reverts to the Primary Migration Database instructions for processing the keyword. TERMINATE The TERMINATE instruction unconditionally stops the migration process, immediately. .Assignment ( = ) The assignment operator equates the variable to the left of the operator to be equal to the value of the expression to the right. This expression can be another variable, a literal string, the result of a SMART built-in function call, or a string formatted from a combination of literal strings and variable values. The variables in this instruction can be SMART predefined variables, or user defined variables. The user defined variables do not need declaration. Their use in an instruction automatically declares the variable. The following examples show the use of the assignment instruction. $Ghab = 'hab' Sets the global variable $Ghab to contain the string "hab". $T0 = $T1 Copies the template, $T1, to the current processing template $T0. $P1 = 'hwndMenu' Set the current template parameter $P1 to contain the string "hwndMenu" str = 'The keyword ' $KEY ' cannot be migrated.' SmOutputNote ( str ) These two instructions create a migration note and places it in the migration comments for the current keyword. Note the concatenation of the literal strings with the contents of the predefined variable $KEY, containing the current keyword string. Related Topics Two MiCL Examples Navigation Links CONTINUE - Event Command Procedures BACK - SmSendToEditor SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.7. Event Command Procedures ΓòÉΓòÉΓòÉ Event Command Procedures Each keyword in the SMART and User Migration Data Base can contain a command set of instructions for custom processing of the migration code required by the keyword. In addition to these standard command sets, there is a special facility to provide you with pre and post migration event commands sets. As an example, you may wish to prompt the user for the variable containing the application HAB at the start of the migration process. You can do this by creating a set of commands to be processed before (pre) the migration process as follows: result = SmPrompt( $Ghab, "Enter HAB variable name.", Ok | Abort ) if result = "Abort" then TERMINATE In order for SMART to process this command set, the commands are entered into the Migration data base under the pseudo-keyword "$$PRE_PROCESS". All pseudo-keywords are designated as migration event command sets and are not used in SMART for any other reason. The following pseudo-keyword designators are provided for your use. $$PRE_PROCESS At the beginning of the migration process, before any files are processed. $$POST_PROCESS At the end of the migration process. All globals and keyword static variables are accessible at this time. $$PRE_FILE Just before the first line of a new file is read. The current filename is accessible in the global variable $GFILE. $$POST_FILE After the end of file is processed and the file is closed. In the processing of Event Command sets many of the MiCL built-in functions are not applicable and will not process. Also, the preloaded variables ($K..., $L..., $Pn, $Tn) and any Static variables ($S...) are not accessible. Only the following built-in MiCL functions are available to event command sets. SmDisplayDlg ( Display_String, Option_Return, Control_Options ) SmGetListName ( Return_Variable ) SmGetListPath ( Return_Variable ) SmGetSmartPath ( Return_Variable ) SmListDlg ( Display_String, Edit_String, Option_Return, String_Return_Variable, Filename ) SmLoadVars ( Filename ) SmPromptDlg ( Display_String, Edit_String, Option_Return, String_Return_Variable, Control_Options ) SmSaveVars ( Filename, [STATIC | GLOBAL] ) SmSendToEditor ( Template ) The Pre and Post Process command sets can best be utilized to load or save the process variables with the functions: SmLoadVars ( Filename ) SmSaveVars ( Filename, [STATIC | GLOBAL] ) These event command sets can also be utilized to provide run-time interaction with the user to obtain variable names or run options that can easily be stored in process global variables for use by any keyword command set during the process run. Interactive dialogs can be created and used with the following built-in functions: SmDisplayDlg ( Display_String, Option_Return, Control_Options ) SmListDlg ( Display_String, Edit_String, Option_Return, String_Return_Variable, Filename ) SmPromptDlg ( Display_String, Edit_String, Option_Return, String_Return_Variable, Control_Options ) Related Topics Preset Variables Pre and Post Command Sets Global, Static and Local Variables Navigation Links CONTINUE - Programming Notes and Tips BACK - MiCL Instructions SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8. Programming Notes and Tips ΓòÉΓòÉΓòÉ Programming Notes and Tips MiCL Basics Preset Variables Two MiCL Examples Pre and Post Command Sets Use of Templates Use of Dialog Functions Migration Control Migration Notes and Comments Global, Static and Local Variables String and Variable Evaluation Launching the Editor Testing MiCL Command Sets Navigation Links CONTINUE - MiCL Basics BACK - Event Command Procedures SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.1. MiCL Basics ΓòÉΓòÉΓòÉ MiCL Basics In general, the SMART Migration Command Language defines a flexible set of commands to be used in the custom migration of identified keywords which may be encountered in a source language. The exception to this is the Pre and Post processing command sets triggered at specific events during the migration process. Once a keyword to be migrated is identified in the source code SMART accesses the currently selected Migration database for records related to the keyword containing: short comments, long comments, templates, prototypes, sample code, commands and references. A command set consists of a number of SMART Migration Command Language instructions, and built-in function calls to affect the specific migration of an encountered keyword. If no commands are programmed for a specific keyword, then the migration is processed using the default actions. Category 000 keywords are left unaffected. Category 010 keywords require a simple literal string replacement. These keywords will be processed automatically without commands and will have the detected keyword replaced by the template string provided in the migration database without evaluation. Category 020 and above are good candidates for SMART command processing. If there are no commands available in the migration database, SMART will simply output the migration code as defined in the options settings for each category. Typically this will simply be a set of migration comments inserted in the output source code, A keyword command set can be as simple as an output of the template into the migration code stream, along with the arguments of the keyword function inserted into the migrated output. /* Dos Delete - OS/2 1.3 to OS/2 2.1 */ /* Second argument is deleted */ /* Template : DosDelete( $P1 ) */ SmMigrateKeyword(T1) In this example the template for this keyword as coded in the migration table is automatically evaluated in the SmMigrateKeyword function replacing the argument of the output keyword API function call with the first argument of the input keyword function. The results of this simple migration follow. Input source code: DosDelete( szTheFile, 0L ); Output migrated source code: DosDelete( szTheFile ); Navigation Links CONTINUE - Preset Variables BACK - NOTES and TIPS NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.2. Preset Variables ΓòÉΓòÉΓòÉ Preset Variables The processing of the keyword commands starts with a number of predefined variables initialized and available to the commands. Process global variables ($Gxxxxxxxx) can be set in any command set and are available to all keyword commands throughout the current migration process. Keyword static variables ($Sxxxxxxxx) are variables that are local to each keyword, but which retain their value throughout the migration process. You can prompt, or otherwise save a value the first time a keyword is processed to use this value throughout the remaining process. At the end of a process run you may save all of the Global and Static variable values into a hard file to be reloaded at the beginning of another migration run. The keyword information variables, $K... contain information about the keyword and are available to the command set. The source code file and line information is available in the preset variables $L... . If the keyword is a function call, the arguments of this call are stored in $P1...$Pn, with the number of arguments stored in the variable $PCNT. Any templates that are in the migration database for the current keyword are available in the predefined variables $T1...$Tn, with the number of available templates stored in $TCNT. The following is an example of a keyword template: WinMessageBox(HWND_DESKTOP, $GhFrame, $P3, $P2, 0, ?Options) Note that the Global variable $GhFrame has been previously initialized. The two arguments $P3 and $P2 come from the input keyword function call arguments (automatically). The last argument, ?Options is a local variable that been set in prior statements before the output instruction for this template. The predefined variable $KIND tells you if an API keyword functional call is embedded in an expression in the source code. This value is important to determine whether a function call can be removed (if standing alone), or can be set to some static return value (if the return value is used as an argument), or simply cannot be migrated and must have a note attached saying so. Navigation Links CONTINUE - Two MiCL Examples BACK - MiCL Basics NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.3. Two MiCL Examples ΓòÉΓòÉΓòÉ Two MiCL Examples In the following example, a single keyword function call will generate several lines of migrated output. The keyword is "SetParent" in a Win 3.1 which appears in the source code as follows: SetParent(hwnd, hwndParent) The SMART migration table templates for this keyword are: .Template =$P2 = WinQueryWindow ($P1, QW_PARENT); =WinSetParent ($P1, $P2, TRUE); =if (($P2 != HWND_DESKTOP) && = ($P2 != HWND_OBJECT)) = WinSetOwner ($P1, $P2) = else = WinSetOwner ($P1, (HWND)0); The command set for the migration of this keyword follows: /* Replace source code for SetParent - Category 030 */ IF $KIND = "TRUE" THEN DO SmSendToEditor( "$LFILE($LLINE:$LCOL)R" ) DISPLAY = "Verify removal and replacement for keyword: " $KEY SmDisplay( DISPLAY, OPTION, ~Yes | ~No | ~Abort ) IF OPTION = "Abort" THEN TERMINATE IF OPTION = "Yes" THEN DO SmRemove(LINE) SmOutputLine( $T1 ) SmOutputLine( $T2 ) SmOutputLine( $T3 ) SmOutputLine( $T4 ) SmOutputLine( $T5 ) SmOutputLine( $T6 ) SmOutputLine( $T7 ) SmNoMigrate( ) SmNoComment( ALL ) NOTE = "Source line removed and code replaced for:" $KEY SmOutputNote( NOTE ) END END ELSE DO string = "*** Unable to migrate : " $KEY SmOutputNote( string ) SmOutputNote("*** Multi-line migration is embedded.") SmNoMigrate( ) END In this example the command processing checks to see if the keyword is standing alone. If the answer is true, then the source code at the point of the keyword is sent to the editor for the user to view. Next a display dialog confirms replacement of the code. If the user responds "Ok" then the seven output templates are used to generate the migrated output code, with the template variables replaced by the values of the input arguments. The standard output comments were supressed and a note was inserted in this migration to indicate the code replacement. The migrated code created from this command set is shown below: // SetParent(hwnd, hwndParent ); SM$:O hwndParent = WinQueryWindow (hwnd, QW_PARENT); // SM$:M1 WinSetParent (hwnd, hwndParent, TRUE); // SM$:M1 if ((hwndParent != HWND_DESKTOP) && // SM$:M1 (hwndParent != HWND_OBJECT)) // SM$:M1 WinSetOwner (hwnd, hwndParent) // SM$:M1 else // SM$:M1 WinSetOwner (hwnd, (HWND)0); // SM$:M1 // Source line removed and code replaced for: SetParent SM$:I In the next example you wish to migrate a user function and modify the calling sequence every place that it appears by inserting a new argument at the front of the argument list. The user is to be prompted the first time that the keyword is encountered, but the response will be saved for all other occurrences. The keyword is "MyMessageBox" in the form of: MyMessageBox( szString, lOptions ); The template for this migration is: MyMessageBox( $Shwnd1, $P1, $P2 ) The command set follows: IF $Shwnd1 = "" THEN DO result = SmPrompt( "Enter variable for MyMessageBox argument 1.", "hwnd", option, $Shwnd1, OK | Abort) IF option = 'Abort' THEN TERMINATE END SmMigrateKeyword( T1 ) In the example above the static variable $Shwnd1 was checked for a value and if none was present the user was prompted for the variable name. Furthermore, if the user terminated out of the entry panel then the process was stopped, otherwise the migration was completed with the keyword template using the value of the static variable $Shwnd1. Navigation Links CONTINUE - Pre and Post Command Sets BACK - Preset Variables NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.4. Pre and Post Command Sets ΓòÉΓòÉΓòÉ Pre and Post Command Sets The preprocess command set can be used to prompt for process run options, global variables that may be used through the migration process, and used to load previous data from an earlier run. For obvious reasons, many of the keyword related built-in functions are not available for use in the event command sets. However, with the use of the MiCL interactive dialog functions you will be able to set process global variables at run time by prompting the user. The following commands provide a good example for the preprocess event command set. These commands are coded into a pseudo-keyword structure in the migration table. .Keyword =999 000 999 $$PRE_PROCESS .SComment=Preprocess Command set .Command = SmGetListPath( LISTPATH ) = $GVARS = LISTPATH "\VARS1.DAT" = SmPromptDlg( "Enter filename for loading process variables:", = $GVARS, OPTION, $GVARS, ~Ok | ~Abort ) = if OPTION = "Abort" then terminate = SmLoadVars( $GVARS ) = if $GHAB = "" then = $GHAB = "hab" = SmPromptDlg( "Enter application HAB variable name:", = $GHAB, OPTION, $GHAB, ~Ok | ~Abort ) = if OPTION = "Abort" then terminate In the example above, the first order of business is to get the current List-of-Files directory path and create a default filename for the process variables file. Once the user has accepted this filename or entered another name in the edit field, then the function is executed to load the variables from the specified file. Next a check is made for the loaded global variable $GHAB to see if it has a valid entry. Note that MiCL initializes a new variable with a null string. Variables are created when referenced. Therefore, when the variable $GHAB was checked in the IF-THEN instruction, the variable was created with a null entry if the variable did not previously exist. In this example, if the global variable was null then we set the value to our default value "hab". Finally, a prompt dialog is created to allow the user to enter the string for the application HAB variable or accept the one displayed. The Post-Process command set allows you the opportunity to execute any functions that you may need at the end of the migration process after all of the migration files have been processed and closed. Typically this may consist of simply saving the static and global variables from the current migration run. Following is a sample of a typical post-processing command set. .Keyword =999 000 999 $$POST_PROCESS .SComment=Post-process Command set .Command = if $GVARS = "" then = do = SmGetListPath( LISTPATH ) = $GVARS = LISTPATH "\VARS1.DAT" = end = SmPromptDlg( "Enter filename for storing process variables:", = $GVARS, OPTION, $GVARS, ~Ok | ~Abort ) = if OPTION = "Abort" then terminate = SmSaveVars( STATIC | GLOBAL ) Note in this example we took advantage of the fact that in the preprocess command set we stored the filename of the variables in a global variable, "$GVARS". Now at the end of the process we can access this stored filename and use it as the default entry item in a prompt to the user. Recalling that the first button in the SmDisplayDlg, SmPromptDlg, and the SmListDlg respond to the keyboard "Enter" key, while the second button responds to the "Esc" key. Since we have placed the natural default filename in the entry field of the prompt, the user can complete the process with this filename by simply pressing the "Enter" key. Related Topics Global, Static and Local Variables Navigation Links CONTINUE - Use of Templates BACK - Two MiCL Examples NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.5. Use of Templates ΓòÉΓòÉΓòÉ Use of Templates Use of a template, along with the MiCL built-in command SmMigrateKeyword is a simple and effective way to migrate an API keyword when the arguments of the call have be changed. With a template for an API migration you have the ability to reorder the arguments, delete any arguments, insert new arguments. The new arguments may be a literal string, the contents of a user prompted variable, or the user selected return from a list of possible arguments from the SmListDlg dialog. The argument can even be the assignment return variable from the source code that may exit in the form of: sReturn = Fcn( Arg1, Arg2, Arg3); The mechanism for this migration maneuver begins with the predefined variables that are available at the beginning of the command set. Each argument of the API keyword function call in the source code is set to the variables $P1-$Pn. The assignment return variable $KRTN contains the variable name of the function return assignment if any exists. All templates found for the current keyword are available in the predefined variables $T1-$Tn. A template is a coding string that is loaded into the migration table dictionary with a tag of ".Template". The template should be coded exactly as it will appear to replace the keyword in the source code, or appear as a generated source code line using the SmMigrateKeyword built-in function. Any spacing, literals, special syntax characters and any other item that is to appear in the output should be placed in the template. The power and flexibility of the template comes from the use of any variables that you may place in the template. During the evaluation of the template in the built-in functions SmMigrateKeyword or SmOutputLine, any variables that start with "$" or "? ". This will include any process Global or keyword Static variables along with predefined variables, and any keyword local variable that begins with "$" or "?". Example: Windows source statement: bChild = IsChild (hWndParent, hWndChild); Migration Table code: .Template =WinIsChild ($P2, $P1) .Command=SmMigrateKeyword( $T1) Migrate output code: bChild = WinIsChild (hWndChild, hWndParent); Note in the simple example above that the parameters of the Win keyword API "IsChild" are reversed in their appearance in the OS/2 migrated code. This was accomplished by simply stating the format of the output in the keyword template coded into the migration table, and then declaring the built-in function SmMigrateKeyword() in the command set. The following hypothetical example makes use of the $KRTN variable and a multiple output migration coding lines. Win statement: sCount = ButtonCount( hWnd, 0L); Migration Table code: .Template=HWND hwndDlg = WinGetDialogFocus( $P1 ); =WinGetButtonCount( HWND_DESKTOP, hwndDlg, &$KRTN ); .Command =IF $KIND = "TRUE" THEN = DO = SmSendToEditor( "$LFILE($LLINE:$LCOL)R" ) = DISPLAY = "Verify code replacement for keyword: " $KEY = SmDisplay( DISPLAY, OPTION, ~Yes | ~No | ~Abort ) = IF OPTION = "Abort" THEN TERMINATE = IF OPTION = "Yes" THEN = DO = SmRemove(LINE) = SmOutputLine( $T1 ) = SmOutputLine( $T2 ) = END = END =ELSE = DO = string = "*** Unable to migrate : " $KEY = SmOutputNote( string ) = SmOutputNote("*** Multi-line migration is embedded.") = SmNoMigrate( ) = END Migrated Output Code: HWND hwndDlg = WinGetDialogFocus( hWnd ); WinGetButtonCount( HWND_DESKTOP, hwndDlg, &sCount); There are a couble of important items to note in this example. As in previous examples when a line of code is to be removed, the code is displayed and the user is requested to verify the removal. This will prevent code removal under unusual coding syntax situations which may garble the output. Predefined variables are used in both templates, including the return variable $KRTN. The second argument in the input source "0L" was not needed, and was discarded by not specifying the predefined argument variable $P2 in either of the templates. You may also not that a constant "HWND_DESKTOP" was inserted in the second template. Related Topics Preset Variables Global, Static and Local Variables Navigation Links CONTINUE - Use of Dialog Functions BACK - Pre and Post Commands NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.6. Use of Dialog Functions ΓòÉΓòÉΓòÉ Use of Dialog Functions Use of the built-in dialog functions SmDisplayDlg , SmPromptDlg, SmListDlg can enable you to create a great deal of interactive and expert-like functionality in the migration process. These three dialog functions provide a great deal of flexibility while allowing the user to select options and provide run-time information where user interaction, verification and choice is required. All three dialogs halt the migration process and wait for user response. In conjunction with the SmSendToEditor , you will have the opportunity to display the source code at the point of the keyword encounter and allow the user to browse the source code to make the selection requested of the dialog. The three dialog functions all display information, wait for user response, and return the response back to the command set program. In each dialog, however, the capabilities are quite different. SmDisplayDlg SmDisplayDlg is a type of message box. The arguments of the function call specify the message to be displayed, a select return variable and a rather unique way to specify up to four buttons to be displayed. The buttons specification depart quite differently from the WinMessageBox call in OS/2 Presentation Manager Programming. In MiCL you simply specify the ID on each of up to four buttons. The ID will appear on the button exactly as specified. You may include a tilde (~) character preceding any character of the button ID to designate an accelerator key for the button. The first button in the specification responds to the "Enter" key and the second button responds to the "Esc" key. When the user presses on of the buttons created for this dialog, the dialog will terminate and the ID string of the button pressed will be returned as the value of the select return variable. At this point you may compare the value of the select return variable with any one of the string IDs to determine appropriate action based on the selection. Note that the button string ID returned does not include any tilde which may have been specified as an accelerator. One other nice feature for each of the three dialogs is their placement recall. If the user moves the placement of any one of the dialogs on the desktop, subsequent creation of the same type of dialog will appear in the location last positioned. In this manner you have the opportunity to position the dialogs and the editor to best suit your needs during the migration process. Let's look at an example of the display dialog. .Command =SmSendToEditor( "$LFILE($LLINE:$LCOL)R" ) =DISPLAY = "Verify code replacement for keyword: " $KEY =SmDisplay( DISPLAY, OPTION, ~Yes | ~No | ~Abort ) =IF OPTION = "Abort" THEN TERMINATE =IF OPTION = "Yes" THEN = ... Note how the three buttons in the above dialog were specified. The button IDs need not be placed in quotes. The IDs will appear case sensitive exactly as they are specified. The variable "OPTION" was used to receive the returned response. SmPromptDlg While SmDisplayDlg can be used as a type of message box, SmPromptDlg is an entry panel dialog. A prompt message string is specified in the arguments of the call to create this dialog. In addition to the prompt string, the other arguments specify the initial entry string, the entry return variable, the button return string and the buttons specification. The initial entry string provides a highlighted default entry for the user. The entry return variable will contain the user's entry string at the termination of the dialog panel. The button return variable and the buttons specification operate identically as in the SmDisplayDlg described above. The following example of the SmPromptDlg function points to a good use of the keyword static variable to recall the previous user entry to be used as the current initial entry string as the dialog is initialized. IF $Shab = "" THEN $Shab = "hab" RTN = SmPromptDlg("Please enter the variable name used for HAB", $Shab, OPTION, $Shab, ~Ok | ~Cancel | ~Abort ) IF OPTION = "ABORT" THEN TERMINATE In this example the keyword static variable $Shab is used to contain the variable name used for the application anchor block. If this static variable is null and has never been set, it is initialized to "hab". Next note that both the initial edit string argument and the entry return arguments both use this same static variable. Using this technique in SmPromptDlg will provide the user with their prior entry as an initial default in the current prompt. You should note two poor techniques in the coding of the command set in the above example. There is no display of the source code immediately preceding the prompt dialog. The user will not know where this prompt is referenced in the source code. The second coding error is not providing the keyword in the display of the prompt. By using The SMART Editor as the SMART editor, and sending the file/line/column_number to the editor will automatically highlight the referenced keyword. However, it is a good programming technique to also identify the name of the keyword in the display or prompt message. Go back and review the previous example for the SmDisplayDlg function. SmListDlg The interactive dialog panel created with SmListDlg presents a number of unique capabilities. Essentially this is a user maintainable, item selectable list box. The list box is loaded from items contained in the file specified in the argument of the call to this function. With the controls on this dialog panel, the user may select one of the list box items, or type a new entry to be returned to the command program and saved in the file for subsequent use. The buttons on this panel, unlike the other two dialog functions, are fixed and not programmable. The list of items to be loaded can be prepared from a simple text editor with one item per line of the file. The user can add items, or delete any item in the list. Double clicking on any list box item will automatically make the selection and terminate the dialog. The item selected will be returned to the command program as the value of the selection return variable. The following example demonstrates the use of the SmListDlg. SmSendToEditor( "$LFile($LLine:$LCol)R" ) SmListDlg("Select the choice for HANDLE replacement", $Shandle, OPTION, $Shandle, "HANDLE.DAT" ) IF OPTION = "Terminate" THEN TERMINATE IF OPTION = "Cancel" THEN DO SmNoMigrate EXIT END SmMigrateKeyword( $T1 ) In this example the file "HANDLE.DAT" contains the following entries: HWND PVOID LHANDLE CHAR * This list box, dialog selection panel is best utilized where a combination of an entry field is combined with a list of multiple selectable items is needed. It provides a user an effective opportunity to view the source code at the point of keyword encounter and select one of several templates or other migration options displayed in this panel. Related Topics Launching the Editor Navigation Links CONTINUE - Migration Control BACK - Use of Templates NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.7. Migration Control ΓòÉΓòÉΓòÉ Migration Control General migration control is achieved with the built-in MiCL functions SmIgnoreKeyword( ), SmNoMigrate( ), along with SmMigrateKeyword( ) and SmRemove( ). SmIgnoreKeyword( ) will cause the processing to skip over the encountered keyword, just as if it did not appear in the migration table. The original source code stays intact and no comments or notes are inserted in the output stream. Essentially this acts like the keyword appeared in an Exclude Keyword file, except that this function is programmatic and can be executed depending upon run time conditions. As an example, it may be necessary to process a keyword by first displaying the source code at the keyword encountered and then asking the user to process the keyword or skip this encounter. If the user responds with "Skip", then the MiCL command can execute the SmIgnoreKeyword( ) function to skip the processing of the keyword. The output remains intact and will appear as if the keyword was not encountered. The following code demonstrates this example: .Command =SmSendToEditor( "$LFILE($LLINE:$LCOL)R" ) =DISPLAY = "Verify migration for keyword: " $KEY =SmDisplay( DISPLAY, OPTION, ~Yes | ~Skip | ~Abort ) =IF OPTION = "Abort" THEN TERMINATE =IF OPTION = "Yes" THEN = SmMigrateKeyword( $T1 ) =ELSE = SmIgnoreKeyword( ) SmNoMigrate( ) will cause the process to go through all of the migration steps, except that the keyword will appear in the output exactly as it did in the source code input, with no change. In this case the original code will appear untouched, but all migration comments and any note generated will appear in the output code. (Note: in comparison, SmIgnoreKeyword will suppress all comments and notes). This function can be used where the migration was exited during the MiCL command set processing and the migration could not be performed and was left to the user. If you simply "EXIT" the command set without executing SmMigrateKeyword, or SmNoMigrate, then the keyword (with all arguments in the case of an API keyword) will be left out of the output code. This may confuse the user to see part of the source code left blank. You may prefer to execute SmNoMigrate and place a note to the user in the output code. An example of SmNoMigrate follows: The source code appears as follows: if (DeleteMenu (hMenu, 2, MF_BYPOSITION) ) MenuProcess(hMenu); The migration table code: .Template =SHORT sID = (SHORT)WinSendMsg ( $P1, MM_ITEMIDFROMPOSITION, = MPFROMSHORT (2), MPVOID) = WinSendMsg ( $P1, MM_DELETEITEM, MPFROM2SHORT(sID,FALSE), = PVOID); .Command =if $KIND = "TRUE" then = do = SmMigrateKeyword( $T1 ) = SmOutputLine( $T2 ) = end =else = do = SmNoMigrate() = DISPLAY = "** No Migration. Embedded Keyword: " $KEY = SmOutputNote( DISPLAY ) = end The resulting output code will appear as follows: if (DeleteMenu (hMenu, 2, MF_BYPOSITION) ) MenuProcess(hMenu); // ** No Migration. Embedded Keyword: DeleteMenu SM$:I // SM$:C // DeleteMenu - Cat:030 Type:010 Area:280 SM$:K // Replace with WinSendMsg and MM_DELETEITEM SM$:S Navigation Links CONTINUE - Migration Notes and Comments BACK - Use of Dialogs NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.8. Migration Notes and Comments ΓòÉΓòÉΓòÉ Migration Notes and Comments There are two MiCL built-in functions that control the output of migration comments and notes. These are SmNoComment( ) and SmOutputNote( ). Migration comments come from the migration table coded under the tags: SComment, LComment, Template, Prototype, and Sample. The user has control over the suppression of any of these comments in the migration options settings. In addition to the user control, the MiCL function call can programmatically suppress any of these comments by specifying the comment tag to be suppressed in the argument of this call. SmOutputNote( ) places a note created in a MiCL Command set in the output stream under the migrated code. Typically these notes are used to advise the user of some alternative action performed during the execution of the command set based upon the user response to a selected option. These notes are placed in comments and are tagged with "SM$:I". With the combinational of these two built-in functions you can control the commented text inserted in the output code following the detection of a keyword. You can replace all standard migration comments with a new set; you can suppress all comments and notes; you can add migration notes to the standard comments. These options are all available with MiCL using SmNoComment and SmOutputNote. Navigation Links CONTINUE - Global, Static and Local Variables BACK - Migration Control NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.9. Global, Static and Local Variables ΓòÉΓòÉΓòÉ Global, Static and Local Variables Variables used in MiCL fall into three major categories: Process Global, Keyword Static and Local. The life and scope of each category is quite different. Process Global variables are designated with the leading characters "$G". Once a global variable is set, it is available to all keyword command sets throughout the process. The value of a global variable can be changed at any time during the process run, by any keyword or event command set. Furthermore, the global variables can be saved at any time during the process run through the execution of the built-in function "SmSaveVars". The saved variables can be restored with their saved values using the function "SmLoadVars". Keyword Static variables behave like global variables except that the scope of the Static variable is contained to the Keyword command set where it has been created. The same static variable name can be used in multiple command sets, however the scope of each of these duplicate variable names is restricted to its own keyword. The Keyword Static variable is ideal for maintaining keyword migration data and options throughout the process run. As in the case of the global variables, the static variables can be saved to a hard file and restored when necessary. Keyword Static variables are designated by the leading characters "$S". The local variable's life only extends to the end of a command set. The value of the variable is only available to the keyword command set where the variable is created and set. Typically it is used for temporary or intermediate storage of keyword data, options and strings related to the individual encounter of a keyword during the migration process. The predefined variables related to keyword context information are all local variables, created automatically during the migration process upon detection of a keyword encounter. A local variable name can begin with any character A-Z, !, ? or _ . Local variables used in template processing with the SmMigrateKeyword and SmOutputLine must begin with a "?" character. All variable names processed in MiCL are case insensitive. The names of control option buttons in the dialog functions are NOT variables but instead, are case sensitive literals. Related Topics Preset Variables Use of Templates String and Variable Evaluation Navigation Links CONTINUE - String and Variable Evaluation BACK - Migration Notes and Comments NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.10. String and Variable Evaluation ΓòÉΓòÉΓòÉ String and Variable Evaluation The evaluation of variables and strings fall into three categories: Templates, Arguments, and assignment expressions. A Template is a string containing embedded variables. When this string is evaluated, the variables are replaced by the string value of the variable while the rest of the evaluated string including all spacing and special characters remain unchanged. Templates can be created within the command set and can be coded in the migration table using the ".Template" tag. Template evaluation is performed on the argument of the following MiCL built-in functions: SmMigrateKeyword ( Template ) SmOutputLine ( Template ) SmSendToEditor ( Template ) Please note that the ONLY variables that are replaced by their string values are those beginning with "$" and "?". Any other character string will be assumed to be part of the template and will be passed unchanged to the output of the evaluation. Any Template enclosed in quotation marks will have the outer marks removed during the evaluation. If the result is required to be contained in quotation then you must place the template string in double quotation. The following are valid template strings: $LFile($LLine) WinSetParent( $P1, ?Param2, TRUE); "'OS2.H'" An example of a template created within the command set may appear as: $T1 = RETURN " = WinSetParent( $P1, $P2, TRUE):" Arguments to MiCL built-in functions other than those evaluated as templates (shown above) are evaluated as either the string value of a variable or a literal string in quotation. The control option button IDs in the dialog functions SmListDlg, SmDisplayDlg, and SmPromptDlg are not evaluated but are used as entered. Any argument variable that has not previously been created will be passed to the output without evaluation. Evaluation of expressions in the assignment instruction combine literal strings and/or variable values. The evaluation of the expression proceeds from left to right after the equal sign (designating an assignment instruction). Spacing is maintained only within the literal strings, enclosed in quotation. All expression elements are concatenated. The following is an example of expression evaluation. $KEY contains "CreateWindow" The command is shown below: DISPLAY = "Unable to migrate: " $KEY ". Keyword is embedded." SmDisplayDlg( DISPLAY, OPTION, Ok | Abort ) The resulting evaluation in the assignment instruction of DISPLAY is: Unable to migrate the keyword: CreateWindow. Keyword is embedded. Related Topics Preset Variables Use of Templates Navigation Links CONTINUE - Launching the Editor BACK - Global, Static, and Local Variables NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.11. Launching the Editor ΓòÉΓòÉΓòÉ Launching the Editor The editor specified in the SMART setup options can be launched from the MiCL built-in function SmSendToEditor( ). The argument of this call is used as one of the arguments of a DosStartSession for the specified editor. Additional arguments can be specified in the setup options for the editor and will be used each time this function is executed. Typically the argument for this function is created as a template to contain the filename, line number, column number and an indicator to open the file as read only. An example of this template argument is shown below: $LFILE($LLINE:$LCOL)R Note that in this example the variables $LFile, $LLine, $LCol are all predefined variables that are automatically set before the execution of any line of code in a command set. This template is specifically designed for The SMART Editor - The SMART Editor. The SMART Editor will accept this parameter and open the specified file at the designated line number. Furthermore the word at the specified column number will be highlighted. A new instance of The SMART Editor will not be created by this call, if SLSTART is designated as the system editor. Instead The SMART Editor will immediately open the file at the point of the keyword encounter as specified by the template shown above. As an additional feature, the use of the optional parameter "/F" in the setup options for SLSTART will force The SMART Editor to popup the specified file without having to select "Open Waiting Files" (F10). It is highly recommended that you create a project instance of The SMART Editor in the use of SMART. Simply create a program object for The SMART Editor and place the project ID in the parameter of this instance with the /P:xxxx option. "xxxx" should be the project ID for this special instance of The SMART Editor. "SMART" could be a good choice for this ID. In a like fashion, identify this instance of The SMART Editor by placing a /P:xxxx parameter in the parameters field of the SMART editor specification in the Setup Options dialog. If you are not using The SMART Editor as your designated SMART editor, the results using SmSendToEditor will depend upon the capabilities of the specified editor. It is important that you halt the migration process after executing this instruction. This will allow your editor to display the source code in an orderly fashion. Executing any one of the dialog functions ( SmListDlg, SmDisplayDlg, and SmPromptDlg ) will temporarily halt the process until the user responds to the dialog. Failure to halt the migration process after executing SmSendToEditor may cause a general OS/2 system failure. Related Topics Use of Dialog Functions Navigation Links CONTINUE - Testing MiCL BACK - String and Variable Evaluation NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 5.8.12. Testing MiCL Command Sets ΓòÉΓòÉΓòÉ Testing MiCL Command Sets You are advised to perform thorough testing of any MiCL programs that you create. MiCL processing does not perform extensive detection and reporting of programming bugs. Unexpected results may occur from programming errors. This version of SMART includes a trace facility for MiCL. To activate MiCL Trace select "Trace MiCL" under the "Migration" main menu item. A display will appear. You can size and move the trace display. Next enter the keyword to trace and press 'Trace Keyword' or press "Trace ALL" to trace all keywords executing MiCL Commands. Once the trace begins, press <Enter> to step through each command line. At the conclusion of tracing through a keyword command set, you may cancel the trace, advance to the next keyword encounter, change the name of the keyword to trace, or terminate the migration process. (Press <Enter> or select the appropriate item under the "Trace" menu on the MiCL Trace Window.) Closing the Trace Facility will cancel the trace and the migration process will proceed naturally through the process. The best way to test your MiCL programs to create a UDMD containing the MiCL commands as they will appear in the migration table. Then, prepare a sample source code file containing various different examples demonstrating the use of the programmed keyword. You can quickly create a UDMD from the MiCL commands, and process the test source code with the SMART Migration. Be sure to select the newly created UDMD table as the override migration table. Once you are satisfied with the test results from this small test file, you may wish to process a selected set of files from your actual source code. After you have processed this migration test, carefully review the resulting output to insure that the migration was performed as programmed. Navigation Links CONTINUE - Reference BACK - String and Variable Evaluation NOTES and TIPS SECTION 2 - MiCL Programming CONTENTS ΓòÉΓòÉΓòÉ 6. Reference ΓòÉΓòÉΓòÉ Reference Reserved Words Keyword Identifier Codes Navigation Links CONTINUE - Reserved Words BACK - Testing MiCL CONTENTS ΓòÉΓòÉΓòÉ 6.1. Reserved Words ΓòÉΓòÉΓòÉ Reserved Words The following words are reserved by the SMART Migration Command Language Processor and should not be used as a variable name in your commands. The definition and purpose of these reserved words are found elsewhere in this document. Remember, all command language text not enclosed in quotes is treated as uppercase. Also, user variables cannot start with a dollar sign ($) this is reserved for SMART predefined variables (however $G and $S variables can be custom user identified with up to eight characters). ALL AND BLOCK DEFAULT DO ELSE END EXIT GLOBAL IF KEYWORD LCOMMENT LINE NOT PROTOTYPE OR SAMPLE SCOMMENT SmDisplayDlg SmGetListName SmGetListPath SmGetSmartPath SmIgnoreKeyword SmLoadVars SmMigrateKeyword SmNoComment SmNoMigrate SmOutputLine SmOutputNote SmPromptDlg SmRemove SmSaveVars SmSendToEditor STATIC TEMPLATE TERMINATE THEN Navigation Links CONTINUE - Keyword Identifier Codes BACK - Reference REFERENCE CONTENTS ΓòÉΓòÉΓòÉ 6.2. Keyword Identifier Codes ΓòÉΓòÉΓòÉ Keyword Identifier Codes Keyword Category 000 Informational only 010 Literal replacement 020 Replacement with parameter changes 030 Change with more / less API calls 040 Logic changes required 050 Functionality does not exist 099 Dictionary entry not defined Keyword Type 010 Function 020 Message 030 Symbol 040 typedef 999 Unknown Functional Area - Windows 010 Module-Management 020 Segment 030 Memory-Management 040 Operating-System Interrupt 050 Task 060 Resource-Management 070 String-Manipulation 080 Atom-Management 090 Initialization-File 100 Communication 110 Sound 120 Utility Macros and Functions 130 File I/O 140 Debugging 150 Optimization-Tool 160 Application-Execution 200 Message 210 Window-Creation 215 Multiple-Document Interface 220 Display and Movement 230 Input 240 Hardware 250 Painting 260 Dialogs 270 Scrolling 280 Menu 290 Information 300 System 310 Clipboard 320 Error 330 Caret 340 Cursor 345 Icon 350 Hook 360 Property 370 Rectangle 400 Device-Context 410 Drawing-Tool 420 Color-Palette 430 Drawing-Attribute 440 Mapping 450 Coordinate 460 Region 470 Clipping 480 Line-Output 490 Ellipse and Polygon 500 Bitmap 510 Device-Independent Bitmap 520 Text 530 Font 540 Metafile 550 Device-Control 560 Printer 570 Environment 580 Network 800 WinMem32 810 Windows Macros 820 File Manager Extensions 830 Version Control Extensions 840 ToolHelp Extensions 850 Stress Extensions 860 Shell Extensions 865 Screen Saver Extensions 870 Print Spooling Extensions 875 Pen Windows Extensions 876 Pen Windows Extensions 880 OLE 890 MultiMedia Extensions 891 MMP Extensions 892 DispDib Extensions 895 File Compression Extensions 896 File Compression Extensions 900 Device Driver extensions 905 Dialog Extensions 910 DDEML 911 DDE 915 Dialog Editor Extensions 920 Control Panel Extensions 925 Common Dialogs 926 Color Dialog 930 Common Dialog Errors 940 Typedefines 990 Miscellaneous 999 Functional Area not defined Functional Area - OS/2 010 Module-Management 020 Segment 030 Memory-Management 040 Semaphores 050 Tasks and Threads 060 Resource-Management 070 String-Manipulation 080 Atom-Management 090 Profile-Management 100 Pipes and Queues 110 Sound 120 Utility Macros and Functions 130 File I/O 140 Device Drivers 150 Printing 160 Application-Execution 170 Signals and Monitors 180 Keyboard Interface (Kbd) 190 VIO Interface (Vio) 200 Mouse Inteface (Mou) 210 Window Creation 220 Display and Movement 230 Input 250 Painting 260 Dialog 270 Scrolling 280 Menu 290 Information 310 Clipboard 320 Message 330 Cursor 340 Pointer 350 Hook 370 Rectangle 420 Color-Palette 450 Coordinate 460 Region 480 Line-Output 500 Bitmap 520 Text 530 Font 590 Graphics-Engine 600 Drag-Drop 910 DDE 920 Switch-List 930 Spool-Manager 940 Direct-Device File System 950 Print-Spooling 990 Miscellaneous 999 Functional Area BACK - Reserved Words REFERENCE CONTENTS