<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-51C5DC6C-0CEE-5F44-8578-AEFBEF90FA4D" xml:lang="en"><title>READIMAGE</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>READIMAGE is a command-line tool that provides readable data from

a ROM, ROFS, or E32 image. It can also generate an IBY file from a

SIS file which can be used to generate a data drive image. </p>

<section id="GUID-EB948089-0609-58A1-A87E-5B13B0DF1FE7"><title>Command

syntax</title> <p>Run the following command to use the READIMAGE tool: </p> <p><userinput>readimage [options] &lt;image filename&gt; or &lt;SIS

filename&gt;</userinput> </p> <p>where: </p> <ul>

<li id="GUID-396A2825-6CD1-5E0D-8E2E-40424D57CBBE"><p> <codeph>&lt;image

filename&gt;</codeph> is an input <filepath>image</filepath> file </p> </li>

<li id="GUID-6AB4C51E-F213-5755-BFF7-1416AC024D06"><p> <codeph> &lt;sis

filename&gt;</codeph> is an input <filepath>.sis</filepath> file. </p> </li>

</ul> <p><b>Reading ROM, ROFS and E32 images</b> </p> <p>Run the following

command to read a ROM, ROFS, or E32 image: </p> <p><userinput>readimage

options &lt;ROM/ROFS/E32 imagefile&gt;</userinput> </p> <p>The command

line options are as follows: </p> <table id="GUID-A89CDF05-C34B-5091-96B8-F34F503B102B">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Options</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>-o</codeph>  </p> </entry>

<entry><p>Indicates output file name. </p> </entry>

</row>

<row>

<entry><p> <codeph>-d</codeph>  </p> </entry>

<entry><p>Displays header information about the input image. </p> </entry>

</row>

<row>

<entry><p> <codeph>-s</codeph>  </p> </entry>

<entry><p>Displays the directory structure of the input image. </p> </entry>

</row>

<row>

<entry><p> <codeph>-v</codeph>  </p> </entry>

<entry><p>Displays image headers and the directory structure of the

input image. </p> </entry>

</row>

<row>

<entry><p> <codeph>-e</codeph>  </p> </entry>

<entry><p>Displays the E32 image from the input ROM or ROFS image. </p> </entry>

</row>

<row>

<entry><p> <codeph>-h</codeph>  </p> </entry>

<entry><p>Displays help information. </p> </entry>

</row>

<row>

<entry><p> <codeph>-z &lt;path&gt;</codeph>  </p> </entry>

<entry><p>Extracts all files from the given image to the specified

location. </p> </entry>

</row>

<row>

<entry><p> <codeph>-l &lt;logfile name&gt;</codeph>  </p> </entry>

<entry><p>Logs the image contents in a file. </p> </entry>

</row>

<row>

<entry><p> <codeph>-x &lt;pattern&gt;</codeph>  </p> </entry>

<entry><p>Extracts a single or a set of files from a ROM or ROFS image

into the current directory. The pattern contains set of file names.

For more information about <codeph>&lt;pattern&gt;</codeph>, see <xref href="GUID-C0D7E049-635B-5089-9C2F-55BE2481A77E.dita#GUID-C0D7E049-635B-5089-9C2F-55BE2481A77E/GUID-5ABC32C0-2D45-5A38-81A8-409B1E191007">Extracting a set of files</xref>. </p> </entry>

</row>

<row>

<entry><p> <codeph>-r</codeph>  </p> </entry>

<entry><p>Recursively extracts the files from ROM or ROFS image. This

option is always used with the <codeph>-x</codeph> option. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p> <b>Note</b>: Options are not case-sensitive. READIMAGE

reports an error if an argument is not passed for the -x or -z option. </p> <p> <b><i>Extracting one file</i></b>  </p> <p>The command below

extracts all the files from <filepath>sample.img</filepath> to the <filepath>C:\test</filepath> location. </p> <p><userinput>readimage -z C:\test\

sample.img</userinput> </p> <p> <b><i>Extracting a set of files with

wildcard ?</i></b>  </p> <p>The READIMAGE tool provides the -x option

to extract one or more files from a ROM or ROFS image, based on a

pattern that matches the name of the file. A question mark(?) indicates

to match one instance of any character in a file name, within the

directory. </p> <p>The command below extracts all the <filepath>.exe </filepath> files from the <filepath>\sys\bin</filepath> directory present in

the <filepath>sample.img</filepath> file, whose file name consists

of two characters. </p> <p><userinput>readimage -x \sys\bin\??.exe

sample.img </userinput> </p> <p> <b><i>Extracting a set of files with

wildcard *</i></b>  </p> <p>The READIMAGE tool provides the -x option

to extract one or more files from a ROM or ROFS image, based on a

pattern that matches the name of the file. A star sign(*) indicates

to match zero or more instances of any character in a file name, within

the directory. </p> <p>The command below extracts all the <filepath>.exe</filepath> files from the \sys\bin directory present in the <filepath>sample.img</filepath> file, into the current directory. </p> <p><userinput>readimage -x \sys\bin\*.exe sample.img</userinput> </p> <p>The command

below extracts all the <filepath>.exe</filepath> files from the \sys\bin

directory present in the <filepath>sample.img</filepath> file, into

the C:\test location. </p> <p><userinput>readimage -x \sys\bin\*.exe

-z C:\test sample.img</userinput> </p> <p>The command below extracts

all the .dll files from the \sys\bin\ directory and its sub-directories

present in the sample.img file, into the current directory. </p> <p><userinput>readimage -x \sys\bin\*.dll -r sample.img</userinput> </p> <p><b>Generating an IBY file from a SIS file</b> </p> <p>Run the

following command to generate an <filepath>.iby</filepath> file from

a <filepath>.sis</filepath> file: </p> <p><userinput>readimage -sis2iby

[-tmpdir &lt;path&gt; -outdir &lt;path&gt;] &lt;sisfile&gt;</userinput> </p> <p>The following command-line options are supported when generating

an <filepath>.iby</filepath> file from a <filepath>.sis</filepath> file: </p> <table id="GUID-5033FF35-0597-54EF-BDCC-46D66591F629">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Options</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>&lt;sisfile&gt;</codeph>  </p> </entry>

<entry><p>Input <filepath>.sis</filepath> file. </p> </entry>

</row>

<row>

<entry><p> <codeph> -sis2iby</codeph>  </p> </entry>

<entry><p>Used to generate <filepath>.iby</filepath> file for the

given <filepath>.sis</filepath> file. </p> </entry>

</row>

<row>

<entry><p> <codeph> -tmpdir &lt;path&gt;</codeph>  </p> </entry>

<entry><p>Extracts contents of the <filepath>.sis</filepath> file

to the specified directory. </p> </entry>

</row>

<row>

<entry><p> <codeph>-outdir &lt;path&gt;</codeph>  </p> </entry>

<entry><p>Generates <filepath>.iby</filepath> file in the specified

directory. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>To generate an <filepath>.iby</filepath> file from the

given <filepath>.sis</filepath> file, READIMAGE performs the steps

as follows: </p> <ol id="GUID-6E427F6F-712F-51F5-B6B5-B9B4970017A1">

<li id="GUID-459AE7C1-B254-5FD6-A574-306F847AD989"><p>Reports an error

if the <filepath>.sis</filepath> file is invalid or missing. </p> </li>

<li id="GUID-09E38B54-F6AD-5323-AD7D-FA1F5DCA58B2"><p>Extracts the

contents of the <filepath>.sis</filepath> file into a specified directory,

or the current directory if the path is not specified. A <filepath>.pkg</filepath> script file is extracted from the sis file. </p> </li>

<li id="GUID-A1E4B1C5-1507-5809-B41C-4C26E12F77E8"><p>Creates an <filepath>.iby</filepath> file in the specified directory or the current directory

based on the <filepath>.pkg</filepath> file. </p> </li>

</ol> <p>The <filepath>.sis</filepath> file is created using the package

(PKG) script file. A <filepath>.pkg</filepath> file is a text file

containing statements that define the information needed by the installation

(<filepath>.sis</filepath> ) file creation utility, MAKESIS. </p> <p>For more information about creating <filepath>.sis</filepath> file,

see <xref href="GUID-4BDC9F63-83A1-53A5-91A0-B092AA821755.dita">MakeSIS</xref> Installation file generator syntax. For more information on the

.pkg file format, see <xref href="GUID-6D6C54E2-66DA-5626-A75D-5597469D5BE0.dita">PKG File</xref> in

the <xref href="GUID-2FC268F3-5EC2-40DB-B3EA-0E2D5C6EFCAD.dita">Symbian

C++ Developer Library</xref>. </p> <p>READIMAGE extracts the <filepath>.pkg</filepath> file from the <filepath>.sis</filepath> file. It

then uses the <filepath>.pkg</filepath> file as input to generate

the <filepath>.iby</filepath> file. </p> <p><b><i>Languages and Package-header

section</i></b> </p> <p>The details of Languages and Package-header

sections are written in the <filepath>.iby</filepath> file as comments. </p> <ul>

<li id="GUID-6998D038-C11F-5A1A-ABC8-8967438444AC"><p> <filepath>.pkg</filepath> file </p> <codeblock id="GUID-C35E5D70-C347-55C9-8612-C875D67380A0" xml:space="preserve">&amp;EN

# {"HelloWorld application"}, (0xe8000091), 1, 0, 0, TYPE=SA</codeblock> </li>

<li id="GUID-3B4C9642-0774-5B1F-B5F2-4F7A6B001B6A"><p> <filepath>.iby</filepath> file </p> <codeblock id="GUID-EE292E70-9E4D-53E8-AF9D-0633DE89AE87" xml:space="preserve">// Generated IBY file for the package file: \dump\hwapp\hwapp.pkg

// Languages: EN

// Header: "HelloWorld application" (0xe8000091)</codeblock> </li>

</ul> <p><b><i>Install-file section</i></b> </p> <p>In the Install-file

section, the standard installation files, which are specified with

the installation option <codeph>FF</codeph>, are written using the <codeph>FILE</codeph> or <codeph>DATA OBEY</codeph> file keywords. The <codeph>File</codeph> keyword is used if the file is an E32 image, Otherwise,

the <codeph>Data</codeph> keyword is used. </p> <ul>

<li id="GUID-466E2C48-C6A1-5AAA-9315-125FC9C4D9F0"><p> <filepath>.pkg</filepath> file </p> <codeblock id="GUID-5FF15257-A248-533A-BBED-5D517F1CB988" xml:space="preserve">"file0" - "!:\sys\bin\HelloWorld.exe", FF, VR

"file1" - "!:\private\&lt;process SID&gt;\Apps\AGENDA\Ericsson.txt", FF, VR</codeblock> </li>

<li id="GUID-FE0C0E53-65E7-55FB-A7A0-D268EE74A53B"><p> <filepath>.iby</filepath> file </p> <codeblock id="GUID-3BC88477-86B8-5019-B87D-BABDE6BB60F0" xml:space="preserve">file = "\test\dump\hwapp\file0" "\sys\bin\HelloWorld.exe"

data = "\test\dump\hwapp\sis0\file1" "\private\&lt;process SID&gt;\Apps\AGENDA\Ericsson.txt"</codeblock> </li>

</ul> <p><b><i>Embedded-SIS section</i></b> </p> <p>The details of

the Embedded-SIS section are written using <codeph>#include</codeph> pre-processor directive. </p> <ul>

<li id="GUID-1674C791-9BEF-5E21-90E9-04B4D7EEEFAB"><p> <filepath>.pkg</filepath> file </p> <codeblock id="GUID-0EED436A-74BF-5AC8-84EA-3325E2057F52" xml:space="preserve">@"sis0.sis", (0x101f7771)

@"sis1.sis", (0x101f7773)</codeblock> </li>

<li id="GUID-235D1AD1-2DE1-5414-97A7-2C6A4B6FDAA3"><p> <filepath>.iby</filepath> file </p> <codeblock id="GUID-DF10E57A-DE34-5914-A6B9-1D723F19DF4B" xml:space="preserve">#include "sis0.sis"

#include "sis1.sis"</codeblock> </li>

</ul> <p><b><i>Conditions-block section</i></b> </p> <p>In the Conditions-block

section, the IF statements are written using the <codeph>#if - #else

- #endif</codeph> pre-processor directive block. </p> <p>The condition-primitives

and the functions in the <filepath>.pkg</filepath> file are written

as pre-processor macros. </p> <p>The relational and logical operator

keywords are written using the appropriate operators. </p> <ul>

<li id="GUID-CD902082-FC13-5B1E-A316-2D0B289D9ECA"><p> <filepath>.pkg</filepath> file </p> <codeblock id="GUID-C21BA23D-3D71-56E0-8F6D-5A3448403D07" xml:space="preserve">;Display 2 options to the user

! ({"Option1", "Option1"}, {"Option2", "Option2"})

;Conditional installation

IF option1

    "file0" - "!:\private\10000005\import\InstTest\option1.txt";

ENDIF

IF option2

    "file0" - "!:\private\10000005\import\InstTest\option2.txt";

ENDIF

;Conditional installation

IF (MANUFACTURER) = (1)

    "file1" - "!:\sys\bin\HelloWorld.exe"

ELSEIF (MANUFACTURER) = (4)

    "file1" - "!:\sys\bin\HelloWorld1.exe"

ELSE

    "file1" - "!:\sys\bin\HelloWorld2.exe"

ENDIF

</codeblock> </li>

<li id="GUID-723E919D-4A09-5923-99EC-5B1BBD7D1C08"><p> <filepath>.iby</filepath> file </p> <codeblock id="GUID-A7D26F78-0287-52F9-B1DC-13AD7EEF9594" xml:space="preserve">//Install Options: "OPTION1" "OPTION1" "OPTION2" "OPTION2"

#if defined (option1)

    data = "s:\test\hwapp\file0"

"\private\10000005\import\InstTest\option1.txt";

#endif

#if defined (option2)

    data = "s:\test\hwapp\file0"

"\private\10000005\import\InstTest\option2.txt";

#endif

#if (MANUFACTURER) = (1)

    file = "s:\test\hwapp\file1" "\sys\bin\HelloWorld.exe"

#elseif (MANUFACTURER) = (4)

    file = "s:\test\hwapp\file1" "\sys\bin\HelloWorld1.exe"

#else

    file = "s:\test\hwapp\file1" "\sys\bin\HelloWorld2.exe"

#endif</codeblock> </li>

</ul> <p> <b>Note:</b> Using the <filepath>.iby</filepath> file with

the condition-block statements for the creation of ROM and ROFS images

needs appropriate macro definitions. For the preceding examples, the

macros are defined as follows: </p> <codeblock id="GUID-B79B1372-3B2D-5A7E-9A7C-568302CC7D3F" xml:space="preserve">#define option1 //selecting option1 block

#define MANUFACTURER 4 //selecting second conditional block</codeblock> </section>

</conbody></concept>