home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 15 / CD_ASCQ_15_070894.iso / maj / 2105 / idc.doc < prev    next >
Text File  |  1994-03-16  |  13KB  |  278 lines
  1.  
  2. IDC language is a C-like language. It has the same lexical tokens as C does:
  3. character set,constants,identifiers,keywords, etc. All variables in IDC are
  4. automatic local variables (sic!). A variable can contain:
  5.   - a 32-bit signed long integer
  6.   - a character string (max 255 characters long)
  7. A program in IDC consists of function declarations. A function in IDC returns
  8. a value. There are 2 kinds of functions:
  9.   - built-in functions
  10.   - user-defined functions
  11.  
  12. A function is declared in this way:
  13.  
  14.   static func(arg1,arg2,arg3) {
  15.     ...
  16.   }
  17.  
  18. where arg1,arg2,arg3 are the function parameters,'func' is the function name.
  19. It is not nesessary to specify the types of the parameters because any variable
  20. can contain a string or a number.
  21.  
  22. A variable is declared in this way:
  23.  
  24.   auto var;
  25.  
  26. This declaration introduces a variable named 'var'. It can contain a string
  27. or a number. All C and C++ keywords are reserved and cannot be used as
  28. a variable name. The variable is defined up to end of function.
  29.  
  30. In IDC there are the following statements:
  31.   if (expression) statement
  32.   if (expression) statement else statement
  33.   for ( expr1; expr2; expr3 ) statement
  34.   while (expression) statement
  35.   do statement while (expression);
  36.   break;
  37.   continue;
  38.   return <expr>;
  39.   return;                    the same as 'return 0;'
  40.   { statements... }
  41.   expression;                     (expression-statement)
  42.   ;                         (empty statement)
  43.  
  44. In expressions you can use almost all C operations except:
  45.   ++,--
  46.   complex assigment operations as '+='
  47.   , (comma operation)
  48.  
  49. You can use the following construct in the expressions:
  50.  
  51.   [ s, o ]
  52.  
  53. This means to calculate linear (effective) address for segment 's' offset 'o'.
  54. The calculation is made using the following formula:
  55.  
  56.   (s << 4) + o
  57.  
  58. If a string constant is specified as 's', it denotes a segment by its name.
  59.  
  60. There are 2 type conversion operations:
  61.  
  62.   long( expr )
  63.   char( expr )
  64.  
  65. However, all type conversions are made automatically:
  66.   - operand(s) are converted to 'long'
  67.   - the operation is performed.
  68.  
  69. Exceptions:
  70.  1. binary '+' operation. If the first operand is string type, the second
  71.     operand is converted to a string and the operands are concatenated.
  72.  2. relational operations (such as ==,!=, etc.) If both operands are strings,
  73.     the string comparision is performed, otherwise - they are converted to
  74.     numbers.
  75.  
  76. Built-in functions
  77. ------------------
  78.  
  79. The following conventions are used in this list:
  80.   'ea' is a linear address
  81.   'success' is 0 if a function failed, 1 otherwise
  82.   'void' means that function returns no meaningful value (always 0)
  83.  
  84.  All function parameter conversions are made automatically.
  85.  
  86. A. Utility functions
  87. --------------------
  88. long    MK_FP        (long seg,long off);    // the same as [ seg, off ]
  89. long    _lpoke        (long RAMea,long value); // poke a long integer into RAM
  90.                         // returns old value
  91. long    _poke        (long RAMea,long value);// poke a byte into RAM
  92.                         // returns old value
  93. long    _peek        (long RAMea);        // get a byte from RAM
  94. char    form        (char format,long value); // works as sprintf, takes only
  95.                         // 1 parameter. Specifying %f as a parameter
  96.                         // will lead to abnormal program termination
  97.                         // with bad consequences.
  98.                         // The resulting string should
  99.                         // be less than 255 characters.
  100. char    substr        (char str,long x1,long x2); // substring [x1..x2-1]
  101.                         // if x2 == -1, then till end of line
  102. long    strstr        (char str,char substr);    // find a substring, -1 - not found
  103. long    strlen        (char str);        // calculate length
  104. long    xtol        (char str);        // ascii hex -> number
  105.                         // (use long() for atol)
  106. success    AssignKey    (char action,long key);    // assign a key to an action
  107.                         // meaningful only before the main
  108.                         // menu is constructed
  109. success    Jump        (long ea);        // move cursor to ea
  110.                         // screen is refreshed at the end
  111.                         // of IDC execution
  112.  
  113. B. Functions that change program representation
  114. -----------------------------------------------
  115. void    DeleteAll    ();            // delete ALL information
  116.                         // about the program
  117. long    MakeCode    (long ea);        // convert to instruction
  118.                         // returns number of bytes
  119.                         // occupied by the instruuction
  120. success    MakeName    (long ea,char name);    // assign a name to a location
  121. success    MakeComm    (long ea,char comment);    // give a comment
  122. success    MakeArray    (long ea,long nitems);    // convert to an array
  123. success    MakeStr        (long ea,long size);    // convert to ASCII string
  124. success    MakeByte    (long ea);        // convert to byte
  125. success    MakeWord    (long ea);        // convert to word
  126. success    MakeDword    (long ea);        // convert to double-word
  127. success    MakeQword    (long ea);        // convert to quadro-word
  128. success    MakeTbyte    (long ea);        // convert to 10 bytes (tbyte)
  129. void    MakeUnkn    (long ea);        // convert to 'unknown'
  130. success    OpDec        (long ea);        // operands are decimal
  131. success    OpChar        (long ea);        // operands are characters
  132. success    OpOffset    (long ea,long segbase);    // operands are offsets
  133.                         // if segbase==-1, then operands aren't offsets
  134. success    OpSegment    (long ea);        // operands are segments
  135. success    OpNum        (long ea);        // operands are numbers
  136. success    OpAlt1        (long ea,char opnd);    // manually enter 1st operand
  137. success    OpAlt2        (long ea,char opnd);    // manually enter 2nd operand
  138. void    MakeVar        (long ea);        // the location is 'variable'
  139. success    MakeProc    (long ea,long fl);    // fl=0: no proc, fl=1: near proc, fl=2: far proc
  140. success    MakeEndp    (long ea,long fl);    // fl=0: no endp,1: endp
  141. void    ExtLinA        (long ea,long n,char line); // insert an additional line before the generated ones
  142. void    ExtLinB        (long ea,long n,char line); // insert an additional line after the generated ones
  143. void    DelExtLnA    (long ea,long n);    // delete an additional line before the generated ones
  144. void    DelExtLnB    (long ea,long n);    // delete an additional line aftr  the generated ones
  145. success    JmpTable    (long jmpea,long tableea,long nitems);    // define a jump table
  146. void    PatchByte    (long ea,long value);    // change a byte
  147. void    SetFlags    (long ea,long flags);    // change internal flags for ea
  148. success    SetReg        (long ea,char reg,long value); // set value of segment register
  149.  
  150. C. Functions that produce output files
  151. --------------------------------------
  152. void    WriteMap    (char file);        // produce a .map file
  153. void    WriteTxt    (char file,long ea1,long ea2); // produce an .asm file
  154. void    WriteExe    (char file);        // produce an executable file
  155.  
  156. D. Informational functions
  157. --------------------------
  158. long    GetFlags    (long ea);        // get internal flags for ea
  159. long    Byte        (long ea);        // get a byte at ea
  160. long    Word        (long ea);        // get a word at ea
  161. long    Dword        (long ea);        // get a double-word at ea
  162. long    LocByName    (char name);        // -1 - no such name
  163. long    SegByBase    (long base);        // -1 - no such segment
  164. long    MinEA        ();            // the minimal address defined in the program
  165. long    MaxEA        ();            // the maximal address defined in the program
  166. long    ScreenEA    ();            // the current screen ea
  167. long    BeginEA        ();            // where execution starts
  168. long    GetReg        (long ea,char reg);    // get segment register value
  169.                         // -1 - undefined or error
  170. long    FirstSeg    ();            // returns start of the first
  171.                         // segment, -1 - no segments
  172. long    NextSeg        (long ea);        // returns start of the next
  173.                         // segment, -1 - no more segs
  174. long    SegStart    (long ea);        // returns start of the segment
  175.                         // -1 if bad address passed
  176. long    SegEnd        (long ea);        // return end of the segment
  177.                         // this address doesn't belong
  178.                         // to the segment
  179.                         // -1 if bad address passed
  180. char    SegName        (long ea);        // returns name of the segment
  181.                         // "" if bad address passed
  182. long    NextAddr    (long ea);        // returns next defined address
  183.                         // -1 if no such address exists
  184. long    PrevAddr    (long ea);        // returns prev defined address
  185.                         // -1 if no such address exists
  186. long    NextHead    (long ea);        // returns next defined item address
  187.                         // -1 if no such address exists
  188. long    PrevHead    (long ea);        // returns prev defined item address
  189.                         // -1 if no such address exists
  190. long    NextNotTail    (long ea);        // returns next not tail address
  191.                         // -1 if no such address exists
  192. long    PrevNotTail    (long ea);        // returns prev not tail address
  193.                         // -1 if no such address exists
  194. long    ItemEnd        (long ea);        // returns address past end of
  195.                         // the item
  196. long    ItemSize    (long ea);        // returns item size, min answer=1
  197. char    LineA        (long ea,long num);    // get additional line before generated ones
  198. char    LineB        (long ea,long num);    // get additional line after generated ones
  199. char    Comment        (long ea);        // get comment
  200. char    AltOp1        (long ea);        // get manually entered 1st operand
  201. char    AltOp2        (long ea);        // get manually entered 2nd operand
  202.  
  203. E. Functions that change global settings
  204. ----------------------------------------
  205. long    StringEnd    (long asciiendchar);    // set current ASCII end character
  206.                         // returns old value
  207. long    StringStp    (long asciistopchar);    // set current ASCII break character
  208.                         // returns old value
  209. long    LowVoids    (long lowlimit);    // set current low limit for voids
  210.                         // returns old value
  211. long    HighVoids    (long highlimit);    // set current high limit for voids
  212.                         // returns old value
  213. long    TailDepth    (long taildepth);    // set current tail depth
  214.                         // returns old value
  215. long    Direction    (long direction);    // set current search direction
  216.                         // returns old value
  217. long    Analysis    (long analysis);    // enable/disable auto analysis
  218.                         // returns old value
  219. long    Tabs        (long tabulations);    // enable/disable tabulations in output file
  220.                         // returns old value
  221. long    Comments    (long comments);    // enable/disable automatic comments
  222.                         // returns old value
  223. long    Voids        (long voids);        // enable/disable void marks display
  224.                         // returns old value
  225. long    XrefShow    (long xrefshow);    // enable/disable cross-references display
  226.                         // returns old value
  227. long    Indent        (long indent);        // set indention for instruntions
  228.                         // returns old value
  229. long    CmtIndent    (long cmtindent);    // set indention for comments
  230.                         // returns old value
  231. long    AutoShow    (long autoshow);    // enable/disable autoanalysis display
  232.                         // returns old value
  233. success    SetPrcsr    (char processor);    // set processor type
  234.                         
  235. F. Functions that interact with the user
  236. ----------------------------------------
  237. char    AskStr        (char defval,char prompt); // ask a string
  238. long    AskAddr        (long defval,char prompt); // -1 - no or bad input
  239. long    AskSeg        (long defval,char prompt); // -1 - no or bad input
  240. char    AskIdent    (char defval,char prompt);
  241. void    Message        (char str);        // show a message in messages window
  242. void    Warning        (char str);        // show a warning a dialog box
  243. void    Fatal        (char str);        // exit IDA immediately
  244.  
  245. G. Functions that work with segments
  246. ------------------------------------
  247. success    SegCreate    (long startea,long endea,long base,long use32,long alignment,long combination);
  248. success    SegDelete    (long segea);
  249. success    SegBounds    (long segea,long startea,long endea);
  250. success    SegRename    (long segea,char name);
  251. success    SegClass    (long segea,char class);
  252. success    SegAlign    (long segea,long alignment);
  253.     #define saAbs       0    // Absolute segment.
  254.     #define saRelByte  1    // Relocatable, byte aligned.
  255.     #define saRelWord  2    // Relocatable, word (2-byte, 16-bit) aligned.
  256.     #define saRelPara  3    // Relocatable, paragraph (16-byte) aligned.
  257.     #define saRelPage  4    // Relocatable, aligned on 256-byte boundary (a "page"
  258.                         // in the original Intel specification).
  259.     #define saRelDble  5    // Relocatable, aligned on a double word (4-byte)
  260.                         // boundary. This value is used by the PharLap OMF for
  261.                         // the same alignment.
  262.     #define saRel4K    6    // This value is used by the PharLap OMF for page (4K)
  263.                         // alignment. It is not supported by LINK.
  264. success    SegComb        (long segea,long combination);
  265.     #define scPriv     0    // Private. Do not combine with any other program
  266.                             // segment.
  267.     #define scPub      2    // Public. Combine by appending at an offset that meets
  268.                         // the alignment requirement.
  269.     #define scPub2     4    // As defined by Microsoft, same as C=2 (public).
  270.     #define scStack    5    // Stack. Combine as for C=2. This combine type forces
  271.                         // byte alignment.
  272.     #define scCommon   6    // Common. Combine by overlay using maximum size.
  273.     #define scPub3     7    // As defined by Microsoft, same as C=2 (public).
  274. success    SegAddrng    (long segea,long addrng);
  275. long    SegByName    (char segname);        // returns segment base
  276. success    SegDefRef    (long segea,char reg,long value);
  277.                         // set default value for segment reg
  278.